---
title: 套件相依關係圖 — 誰依賴誰、走什麼形狀
brand: Guidant AI · **架構手冊**
eyebrow: 架構手冊 · 工程版 · 2026-08-31（隨第四階段各棒更新）
h1: 套件相依關係圖
lede: 這頁給**工程與發版決策**看：24 支現役套件＋主專案之間的實際依賴邊——誰依賴誰、是正常的直接依賴還是走 port、哪幾條是已知要償還的債。發版順序與「拔掉一支影響誰」直接從這頁讀。目標架構的規則只有一條：**積木只准踩地基，積木之間的協作一律經宿主接線**。
chips: [{text: 工程版, kind: accent}, {text: 現況含 3 條已知債, kind: warn}]
---

## 30 秒版 {#tldr nav="30 秒版"}

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

## 現況依賴圖 {#current nav="現況圖"}

```{.mermaid cap="圖 1 — 現況：實線＝pyproject 宣告的直接依賴；紅線＝已知債（不該存在的邊）；灰虛線＝port 接線（執行期由宿主注入，非套件依賴）"}
%%{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
```

## 邊的分類與清單 {#edges nav="邊清單"}

| 類型 | 邊 | 狀態 |
|---|---|---|
| ✅ 正常 | 全部套件 → 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 等 | 執行期宿主注入，套件之間互不知道對方存在 |

## 發版順序怎麼讀 {#release nav="發版順序"}

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

## 第四階段會改寫的邊（預告） {#future nav="即將變動"}

| 棒 | 圖上的變化 |
|---|---|
| ~~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 講目標規則，本頁講現況實邊。第四階段每棒收口，首腦驗收時順手更新本頁的邊與預告表。