架構手冊 · 工程版 · 2026-08-31（隨第四階段各棒更新）

套件相依關係圖

這頁給工程與發版決策看：24 支現役套件＋主專案之間的實際依賴邊——誰依賴誰、是正常的直接依賴還是走 port、哪幾條是已知要償還的債。發版順序與「拔掉一支影響誰」直接從這頁讀。目標架構的規則只有一條：積木只准踩地基，積木之間的協作一律經宿主接線。

工程版現況含 3 條已知債

§1

30 秒版

規則一條：功能套件只准直接依賴 jedi-common（地基）；套件互相要資料，走宿主接線盤的 port——所以正常的依賴圖非常扁平。
現況有 3 條「不該存在的邊」（已知債，各有追蹤）：participant→iam 的 ORM 直連、license-runtime→身分 view 的 raw SQL、issue→file-upload 的直接 import（此條為明確上下游，經裁定保留）。
發版順序：jedi-common 永遠最先；其他套件彼此無依賴可平發。
本頁隨第四階段各棒收口更新——flow_control 搬遷（CM-1487）與分家會改寫流程區的邊。

§2

現況依賴圖

%%{init: {'theme':'base','themeVariables':{'primaryColor':'#E2F0F1','primaryTextColor':'#14201F','primaryBorderColor':'#0E7C86','secondaryColor':'#EEF2F3','secondaryTextColor':'#14201F','tertiaryColor':'#FBFCFC','tertiaryTextColor':'#14201F','lineColor':'#4A5A5C','textColor':'#14201F','mainBkg':'#E2F0F1','nodeBorder':'#0E7C86','nodeTextColor':'#14201F','edgeLabelBackground':'#FBFCFC','titleColor':'#14201F','clusterBkg':'#FBFCFC','clusterBorder':'#E4EAEB'}}}%%
flowchart TB
    HOST["Guidant AI 主專案（宿主）<br/>依賴全部套件＋負責接線"]

    subgraph P1["功能套件（彼此零直接依賴）"]
        IAM["jedi-iam 0.1.0"]
        PART["jedi-participant（新，未發版）"]
        FCTRL["jedi-flow-control（過渡名，未發版）<br/>190 檔；24 支留主專案待分家"]
        NOTIF["jedi-notification 0.0.11"]
        FILEUP["jedi-file-upload 0.0.23"]
        SURVEY["jedi-survey 0.0.32"]
        ISSUE["jedi-issue 0.0.18"]
        OSCALV2["jedi-oscal-v2 2.2.3"]
        FE2["jedi-flow-engine 0.0.35"]
        OTHERS["bulletin／system-menu／system-config<br/>device／information-system／log<br/>ai-bot／integrity／license-runtime<br/>log-forwarding／remote-agent／project"]
    end

    COMMON["jedi-common 0.0.33（地基）"]

    HOST --> P1
    P1 --> COMMON
    ISSUE -->|"9 處 import<br/>（裁定保留：明確上下游）"| FILEUP
    PART -.->|"🔴 債①：6 支 ORM 直連身分表<br/>→ CM-1484 改 IUserDirectory port"| IAM
    OTHERS -.->|"🔴 債②：license-runtime raw SQL<br/>直打 v_user_capabilities view<br/>→ 隨下次動該套件償還"| IAM
    linkStyle 3 stroke:#C0392B,stroke-width:2px
    linkStyle 4 stroke:#C0392B,stroke-width:2px

圖 1 — 現況：實線＝pyproject 宣告的直接依賴；紅線＝已知債（不該存在的邊）；灰虛線＝port 接線（執行期由宿主注入，非套件依賴）

§3

邊的分類與清單

類型	邊	狀態
✅ 正常	全部套件 → jedi-common	唯一允許的直接依賴（D16 唯一例外）
✅ 正常	主專案 → 全部套件	宿主裝積木，天經地義
✅ 裁定保留	jedi-issue → jedi-file-upload（9 處）	明確上下游非疆界破口（3.5 裁定）
🔴 債①	jedi-participant → jedi-iam（6 支 ORM relationship 直連 User 表）	CM-1484 追蹤；IUserDirectory port 已備妥，排 4.2 後償還；主專案另有 10 支同病 repo 一併評估
🔴 債②	jedi-license-runtime → 身分疆界（raw SQL 直打 `v_user_capabilities` view）	STATE backlog；隨下次動該套件償還（FR-062 當時無名冊 port，屬歷史合理）
🔴 債③	jedi-project → 主專案（3 支 dto import `app.common.dto.base_dto`，方向整個反了）	4.2 設計稿實查發現；D-2 裁定隨「jedi-project 併入 task 平台包」一併修
⚪ port（非依賴）	各套件宣告的 IUserDirectory／INotifier／檔案存取／設定讀取／IProjectRoleGuard 等	執行期宿主注入，套件之間互不知道對方存在

§4

發版順序怎麼讀

jedi-common 動了 → 它先發，其他套件的 floor 檢查一輪（3.5 抓過兩支 floor 過低：notification/system-menu 用到 0.0.30 才有的東西卻掛 >=0.0.23——pip 解到舊版就 import 炸）。
其他套件彼此無依賴 → 可平發（CM-1473 十一支平發實證）。
拔掉一支影響誰：看誰的箭頭指向它——現況只有主專案（全部）與 issue→file-upload 一條；debt 邊償還後更乾淨。

§5

第四階段會改寫的邊（預告）

棒	圖上的變化
~~CM-1487（flow_control 搬遷）~~ ✅ 已兌現	jedi-flow-control（過渡名）已入圖——190 檔搬入；24 支留主專案（16 支依賴未套件化模組＋D-4 四支＋2 連帶），清單見 CM-1487
4.2 第 2 步分家	flow_control 節點分裂：通用半＋jedi-project 種子 → task 平台包（新的第 1.5 層，功能套件會依賴它）；稽核半 → 稽核插件；債③ 隨此修掉
P13（OSCAL）	oscal-v2 補讀取面；oscal → flow_control 單向邊定案
P11（問卷合併）	task_survey 併入 survey，主專案少一塊
CM-1484 償還	債① 紅線消失，改 port 虛線

🔴 維護慣例：本頁與 design.md §8（三層架構目標圖）互補——§8 講目標規則，本頁講現況實邊。第四階段每棒收口，首腦驗收時順手更新本頁的邊與預告表。