---
title: 模組化路線圖 — 白話進度總覽
brand: Guidant AI · **架構手冊**
eyebrow: 架構手冊 · FR-069 模組化 · living
h1: 五個階段、現在在哪、還剩多少
lede: 這頁是全案的**進度入口**——只講階段、工作量、進度。**FR-069 四階段已於 2026-09-01 全數收口**，本頁的套件族譜即終態快照；「為什麼這樣決定」的全文在 [FR-069 站的 design.md](../FR-069-2608-jedi-module-extraction/design.md)（D1–D16 決策表）。本頁隨每棒收口更新。
chips: [{text: 五階段全收（2026-09-01）, kind: ok}, {text: 現役 25 支套件, kind: accent}, {text: 平台化方向已拍板, kind: plain}]
---

## 這案子在做什麼（一句話） {#what nav="做什麼"}

把後端 40 個模組裡「別的產品也用得到」的能力，一支支抽成可獨立安裝的 jedi-* 套件；目標是新產品「裝套件就有 API 可用」，不用重寫。

## 全案地圖 {#map nav="全案地圖"}

::: statgrid
::: stat
[25]{.v}[現役套件（終態，＝主專案 pin 數）]{.k}
:::
::: {.stat .ok}
[16]{.v}[完全體插件（自帶 route，裝上就有 API）]{.k}
:::
::: {.stat .accent}
[18]{.v}[本 arc 發版套件（CM-1473 十一支＋CM-1499 七支）]{.k}
:::
::: stat
[10]{.v}[已退役刪除的套件／塊]{.k}
:::
:::

```{.mermaid cap="圖 1 — 五階段路線圖與現在位置"}
%%{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','actorBkg':'#E2F0F1','actorTextColor':'#14201F','actorBorder':'#0E7C86','actorLineColor':'#C7D1D2','signalColor':'#4A5A5C','signalTextColor':'#14201F','labelBoxBkgColor':'#EEF2F3','labelBoxBorderColor':'#C7D1D2','labelTextColor':'#14201F','loopTextColor':'#14201F','noteBkgColor':'#F6EBD5','noteTextColor':'#14201F','noteBorderColor':'#9C6B12','activationBkgColor':'#EEF2F3','activationBorderColor':'#C7D1D2','sequenceNumberColor':'#FFFFFF'}}}%%
flowchart LR
  P1["第一階段<br/>抽五支新套件<br/>✅ 全收"] --> P2["第二階段<br/>延伸表收斂<br/>✅ 全收"]
  P2 --> P25["2.5 階段<br/>jedi-iam 合併<br/>✅ 全收"]
  P25 --> P3["第三階段<br/>老套件升級插件<br/>✅ 全收＋發版完成"]
  P3 --> P4["第四階段<br/>核心能力抽取<br/>✅ 全收（2026-09-01）"]
  P4 --> END["終局<br/>平台化路線已拍板<br/>task 平台包＋功能插件"]
```

## 五階段表 {#phases nav="五階段"}

| 階段 | 內容 | 工作量 | 進度 |
|------|------|--------|------|
| 第一階段 | 抽五支新套件＋common/ 工具上移（P0–P8） | 8 棒 | ✅ 全收（七支套件發版） |
| 第二階段 | 延伸表收斂＋查詢層擴充（.10–.12） | 3 棒 | ✅ 全收 |
| 2.5 階段 | 身分四套件合併成 jedi-iam＋主專案身分程式收進去 | 7 棒＋1 改名棒 | ✅ 全收（.13–.18＋.H 補搬＋CM-1464 改名） |
| 第三階段 | 既有老套件升級「隨插即用」插件（補殼） | 6 棒（CM-1467–1472）：完全體 4 支＋補殼 10 支＋退役刪 4 支 | ✅ 全收＋發版完成（2026-08-31，CM-1473） |
| 第四階段 | 核心能力抽取（CM-1475–1483 九棒＋掃卡補洞） | 4.A 地基→4.B registry→P12 participant→4.2 flow_control 分家四步→P9 檢測／P10 AI分類→P11 問卷合併→P6 儀表板→三包定名 | ✅ 全收（2026-09-01）＋發版 CM-1499＋收官串（1497/1498/1500/arc-review） |
| 終局選項 | 產品平台化 | task 平台包（`jedi-task-platform`：原 jedi-project 種子＋flow_control 骨架半）＋功能插件生態 | **方向已拍板（2026-08-31）**：project＝插座不是插頭；flow_control 分家＝複用前提。決策全文見[專案平台化決策頁](project-platform-decision.md) |

## 2.5 階段＋第三階段棒次現況 {#stage25 nav="棒次現況"}

**2.5 階段（jedi-iam 合併）全收**：.13 地基／.14 login／.15 mfa+captcha／.16 中介層（抓到 X-Tenant-ID:0 真提權洞並修掉）／.17 清理／.H 補搬／.18 收口（CM-1455–1460、CM-1466），加改名棒 CM-1464（jedi-identity → jedi-iam，PM 定調）。

**第三階段（老套件升級插件）六棒全收（2026-08-31）**：

| 棒次 | 卡號 | 內容 | 狀態 |
|------|------|------|------|
| 3.1 | CM-1467 | jedi-iam 完全體（route 上移 39 條、api/auth/ 刪除）——**範本棒，照抄要點 8 條由此立** | ✅ Done |
| 3.2 | CM-1468 | jedi-file-upload 補殼 | ✅ Done |
| 3.3 | CM-1469 | jedi-notification 補殼 | ✅ Done |
| 3.4 | CM-1470 | jedi-flow-engine 輕量升級（route 歸屬併第四階段流程疆界設計） | ✅ Done |
| 3.5 | CM-1471 | 輕量批七支（bulletin／system-menu／system-config／device／information-system／issue／log）——其中 system-menu／issue／log 升完全體 | ✅ Done |
| 3.6 | CM-1472 | 退役執行——刪 jedi-oscal v1／resource-store／department／jedi_system_log 壞半邊 | ✅ Done |
| 發版棒 | CM-1473 | 11 支發 Nexus＋主專案還原 pin＋四支身分轉發殼（auth/login/mfa/captcha）退役刪除（24→20 支） | ✅ Done |

**第四階段（核心抽取）九棒開打**：

| 棒次 | 卡號 | 內容 | 狀態 |
|------|------|------|------|
| 4.A | CM-1475 | 地基：D17/D18 通則入 design.md＋套件分類地圖＋readmodel 定位 | ✅ Done（③搬遷裁決後併入 P12 步驟 0） |
| 清債 | CM-1474 | 兩張舊表 DROP（孤兒表退役＋project_extensions 收尾）——P-like 雙路徑驗證過 | ✅ Done |
| 4.B | CM-1476 | AI 儀表板 registry 改套件自註冊＋修 4 壞條目 | ✅ Done |
| 4.1（P12） | CM-1477 | jedi-participant 抽出（核心環鑰匙棒；readmodel 櫃檯建置） | ✅ Done（identity JOIN 償還→CM-1484） |
| 4.2 設計 | CM-1478 | 流程疆界設計稿（切線盤點通用 12/稽核 22/待判 12＋D-1～D-9）＋白話改寫 | ✅ Done（D-1～D-9 全數拍板） |
| 4.2 前置 | CM-1485 | flow-engine 用量盤點——camunda 程式側死透/執行面活著是唯一引擎/死碼三類清單 | ✅ Done |
| 4.2 退役 | CM-1486 | flow-engine 死碼清除 4,351 行（camunda 通道/wecm/停用 route/dark stub）＋兩支查詢搬 readmodel | ✅ Done |
| 4.2 步 1 | CM-1487 | flow_control 搬遷成 jedi-flow-control（190 檔；runner 煞車修正「226 檔比照 P12」——16 支依賴未套件化模組留守，清單=第 2 步開工名單） | ✅ Done |
| 4.2 步 2 | CM-1488 | 分家——通用流程層下沉＋稽核歸位＋16 支解鎖＋D-10 耦合度材料 | 🔄 跑著 |
| 4.2 步 3/4 | 待開卡 | 任務型別改申報制（問卷審核=第一案例）→ 打包上 Nexus | ⬜ 步 2 後 |
| 4.3（P13） | CM-1479 | OSCAL 疆界中間路線 | ⬜ 4.2 後 |
| 4.4（P9） | CM-1480 | jedi-detection（先過服務化評估） | ⬜ 可與 4.5 平行 |
| 4.5（P10） | CM-1481 | jedi-evidence-classification | ⬜ |
| 4.6（P11） | CM-1482 | task_survey 併入 jedi-survey | ⬜ |
| 4.7（P6） | CM-1483 | AI 儀表板框架（收尾棒） | ⬜ 排最後 |

::: {.callout .decided}
**完全體 vs 半體（2026-08-31 現況）**

**完全體插件**（route 在套件內，裝一行就有 API、拔一行就消失）：jedi-iam、jedi-system-menu、jedi-issue、jedi-log。**半體**（已補 register 殼但 route 留主專案，各有實查理由——多半是 route 吃主專案業務 service）：file-upload、notification、flow-engine、bulletin、system-config、device、information-system。半體升完全體的門檻（身分脈絡名冊、流程疆界）都排在第四階段。
:::

## 套件族譜：終態（26 支的去向） {#genealogy nav="套件族譜"}

**這節在講什麼：每一支套件從哪裡來、最後變成什麼。** FR-069 四階段已於 **2026-09-01 全數收口**，
本節即**終態**，不再是滾動快照。

::: {.callout}
**怎麼數才對**：本 arc 期間曾同時存在的套件目錄共 **26 支**（含過渡目錄名與待退役者）。
收口後 **現役 25 支**（＝磁碟目錄數＝主專案 `pyproject.toml` pin 數，兩者實查相符），
**退役刪除 10 支／塊**。25 + 10 ≠ 26 是因為多數退役者是**被合併**而非憑空消失
（四支身分套件合成 1 支、兩支改名不算新增）。
:::

### ✅ 現役 25 支——終態表

| 套件 | 版號 | 從什麼變成什麼 | 形態 |
|---|---|---|---|
| **jedi-iam** | 0.1.0 | jedi-auth＋jedi-login＋jedi-mfa＋jedi-captcha（四合一）＋主專案身分中介層／登入編排 | 完全體（39 route） |
| **jedi-task-platform** | 0.1.0 | jedi-project（種子）＋flow_control 通用任務半（分家下沉） | 完全體（10 route）／**插座** |
| **jedi-compliance-audit** | 0.0.1 | flow_control 稽核半（輪次／AP／AR／POA&M／覆核／審閱） | 完全體（5 route） |
| **jedi-participant** | 0.0.1 | 主專案 participant 模組（~90 檔） | 完全體（10 route） |
| **jedi-detection** | 0.0.1 | 主專案 detection_tools＋detection_execution（147 支，基準庫 5.4MB 隨包） | 完全體（35 route） |
| **jedi-evidence-classification** | 0.0.1 | 主專案 AI 佐證分類引擎（~42 檔） | 完全體（10 route） |
| **jedi-ai-dashboard** | 0.0.1 | 主專案儀表板生成框架 | 完全體（2 route） |
| **jedi-survey** | 0.1.1 | 同名老套件 ＋主專案 task_survey 作答層 54 支（P11 合併） | 完全體（32 route） |
| jedi-file-upload | 0.0.23 | 同名老套件 | 完全體（6 route） |
| jedi-system-menu | 0.0.12 | 同名老套件 | 完全體（5 route） |
| jedi-log | 0.0.14 | 同名老套件 | 完全體（2 route） |
| jedi-issue | 0.0.18 | 同名老套件 | 完全體（1 route） |
| jedi-notification | 0.0.11 | 同名老套件 | 完全體（1 route） |
| jedi-flow-engine | 0.0.36 | 同名老套件；清死碼 4,351 行（camunda 殘留），**吸收主專案 BPMN generator／validator 2,758 行** | 執行引擎（無 route） |
| jedi-bulletin | 0.0.13 | 同名老套件 | 半體（route 留宿主，有實查理由） |
| jedi-system-config | 0.0.16 | 同名老套件 | 半體 |
| jedi-device | 0.0.15 | 同名老套件（D11 裁定：不併檢測） | 半體 |
| jedi-information-system | 0.0.4 | 同名老套件 | 半體 |
| jedi-oscal-v2 | 2.2.3 | 同名老套件（v1 退役後的唯一現役 OSCAL 實作） | 領域套件 |
| jedi-common | 0.0.33 | 同名地基；第二階段擴充（JSONB 查詢／身分脈絡包／SessionMixin 正名） | 地基（唯一可被全體依賴者） |
| jedi-ai-bot | 0.0.1 | 第一階段新生（P1，插件契約首例） | 完全體 |
| jedi-integrity | 0.0.1 | 第一階段新生（FR-064 防竄改能力抽出） | 能力套件 |
| jedi-license-runtime | 0.0.1 | 第一階段新生（FR-062 驗簽引擎；執法留宿主） | 完全體（1 route） |
| jedi-log-forwarding | 0.0.1 | 第一階段新生（落地版 log 轉發） | 完全體（1 route） |
| jedi-remote-agent | 0.0.1 | 第一階段新生（FR-039 遠端派工；定 migration 隨包五規則） | 完全體（1 route） |

> 「完全體」＝自帶 route，宿主 `register()` 一行就有 API，且**拔掉就整組消失**（有拔掉測試）。
> 「半體」＝有 container／service 但 route 仍留宿主——第三階段逐支實查後**誠實聲明不搬的理由**
> （多為 route 的 service 實際住在主專案，硬搬會變成套件反向 import）。

### 🗑️ 已退役刪除（10 支／塊）

| 刪掉的 | 去向 / 為什麼 |
|---|---|
| jedi-auth／jedi-login／jedi-mfa／jedi-captcha | 併入 **jedi-iam**；轉發殼一度保留，CM-1473 裁「不發改退役」直接刪 |
| jedi-project（dist 名） | 改名 **jedi-task-platform**，**不留轉發殼**（留殼＝舊名沒退場） |
| jedi-flow-control（過渡目錄名） | 改名 **jedi-compliance-audit**，同樣不留殼；從未上 Nexus |
| jedi-identity（過渡套件名） | PM 定調改名 **jedi-iam**（「identity 只涵蓋你是誰半邊，太狹隘」） |
| jedi-oscal（v1） | **jedi-oscal-v2** 全面取代，順帶消一條 AGPL 依賴 |
| jedi-department／jedi-resource-store | 殭屍（四面查證：程式／venv／DB 表／套件依賴全零引用） |
| jedi_system_log（jedi-log 的壞半邊） | 載入即炸的死碼，真實作在 jedi-common |

> 每一支退役都配**死名守衛**（AST 靜態掃全樹，含 lazy／函式層 import），且守衛本身做過
> 突變驗證（故意植入舊名 → 確認變紅 → 還原）。孤兒守衛也換過軌：刪除的套件必須移出
> `EXTRACTED_PACKAGES` 否則會永久 skip 變成假綠。

### 帳面總結

- 主專案 **40 個模組 → 現役套件 25 支** ＋刻意留在產品本體的四類（見下節）。
- 主專案本 arc 淨變動：**1,456 檔、+57,776 / −74,308 行（淨刪約 16,500 行）**；
  monorepo 側 **2,137 檔、64 commits**。
- **零套件反向 import**（arc-review AST 全掃 25 支確認）；D5 對外契約凍結面
  **231 個 error code 值／424 條 URL／藍圖名逐字零漂移**（機器 diff 證明）。

## 產品本體最後剩什麼——四類 {#host-four nav="主專案剩什麼"}

拆完之後「我們的產品還剩什麼」是最常被問的問題。答案是**四類**，每一類都只有這個產品有
——換第二個產品，這四類要重寫，但 25 支積木照裝。

| 類別 | 這是什麼 | 為什麼不拆 | 實例 |
|---|---|---|---|
| **① 報表櫃檯**（readmodel） | 跨疆界的**純讀**聚合：一張畫面要同時顯示任務＋專案名＋控制項＋稽核輪狀態 | 「要並排顯示什麼」是**這個產品**的設計決定，換產品欄位就換一套。各檔口賣自己的菜，套餐由櫃檯出 | `infra/readmodel/tasks/my_grc_jobs_query.py`（六疆界）、`oscal/ssp_control_implementation_query.py`（七疆界）、`audit/flow_control_dashboard_repo_impl.py`；app 層薄殼在 `app/readmodel/service/`（CM-1507 分子資料夾＋CM-1508 收齊） |
| **② 接線盤**（adapters／ports） | 積木上的插頭（「我要知道誰是使用者」「我要寄信」）由接線盤接上實際服務 | 接什麼、怎麼接是每個產品自己的組裝；套件只宣告 port，不認識實作 | `common/iam_ports.py`、`app/flow_control/adapter/task_existence_query.py`、`app/license/adapter/tenant_directory.py`、`app/remote_agent/adapter/` |
| **③ 組裝根**（wiring／factory） | 這個產品裝哪些積木、哪個租戶開哪些模組、各設定的實際值 | 積木申報「我有哪些設定」（規格書），**值**留產品這邊（D18） | `core/app_factory.py`、`core/iam_wiring.py`、`core/upload_file_wiring.py`、`config/app_modules.py` |
| **④ 業務加工** | 真正只有 Guidant AI 有的業務邏輯與編排 | 換個產品這段根本不存在 | `app/oscal/`（SSP 匯入匯出／diff）、`app/module_frame/`（合規資源庫）、`app/cloud_integration/`（Drive 同步）、`app/project_summary_report/` |

::: {.callout}
**一句話**：積木是通用的，**怎麼組出「Guidant AI 這個產品」是本體的事**。
第二個產品＝同一批積木＋自己的櫃檯＋自己的接線＋自己的組裝。
:::

## 當初討論的 vs 後來長出來的 {#evolution nav="演變"}

| 時點 | 發生什麼 |
|------|---------|
| 8/29 開案 | 只有第一階段 P0–P8；核心凍結「有第二個客戶才抽」 |
| 8/29 當天 | D6/D7：目標升級為隨插即用插件 |
| 8/30 大轉向 | D8：決策者定調「整併本身就是目標、不等客戶」→全解凍，長出第二/三/四階段 |
| 8/30 | D9：身分四套件合併，插入 2.5 階段 |
| 8/30 | D10–D16：疆界盤點批次拍板 |
| 8/30 | PM 定調改名 jedi-iam |
| 8/30–31 | 2.5 七棒全收；.16 抓到 X-Tenant-ID:0 提權洞；驗證瘦身規則七條拍板 |
| 8/31 | 第三階段六棒一天全收；四支老套件升完全體插件；四支死套件刪除；形態知識沉澱成架構手冊（插件指南九節） |
| 8/31 | 發版令下：11 支上 Nexus、四支身分轉發殼不發改退役（CM-1473） |
| 8/31 | 第四階段拆卡九張（CM-1475–1483）；四待裁全拍板 |
| 8/31 | **平台化方向拍板**：project＝插座（被功能套件 register 的平台核心）；flow_control 分家＝流程骨架半供複用＋稽核半自成插件；終局五層包裝定案 |

案子從 8 個工作包長成五階段大工程，是 D8 定調的結果。

## 風險控制 {#risk nav="風險控制"}

::: {.callout .warn}
**驗收與紀律（每棒都適用）**

- 每棒驗收首腦親跑測試＋親打 API，不信 runner 自報。
- 身分棒加驗 401/403/200 實際回應碼。
- 發版、merge main、非 DEV 環境操作一律等決策者令。
- runner「前提被推翻就停」紀律——已救三次（base_repository / is_admin / LoginConfig）。
:::

## 待決事項與 backlog {#pending nav="待決/backlog"}

| 項目 | 說明 |
|------|------|
| 4.2 設計稿（下一個大關） | flow_control 24,600 行切線（骨架 vs 稽核）——設計稿先審後動工；台面判準「換一個產品這段還會一樣嗎」 |
| CM-1450 | 孤兒表 DROP，等令 |
| drop project_extensions 舊表 | 等令，前置 P-like 驗證 |
| backlog | CM-1445 / CM-1452 / CM-1453 / CM-1461（餘 9 支死路徑）/ CM-1463 等清債 |