架構手冊 · FR-069 模組化 · living
這頁是全案的進度入口——只講階段、工作量、進度。FR-069 四階段已於 2026-09-01 全數收口，本頁的套件族譜即終態快照；「為什麼這樣決定」的全文在 FR-069 站的 design.md（D1–D16 決策表）。本頁隨每棒收口更新。
把後端 40 個模組裡「別的產品也用得到」的能力，一支支抽成可獨立安裝的 jedi-* 套件；目標是新產品「裝套件就有 API 可用」，不用重寫。
25現役套件（終態，＝主專案 pin 數）
16完全體插件（自帶 route，裝上就有 API）
18本 arc 發版套件（CM-1473 十一支＋CM-1499 七支）
10已退役刪除的套件／塊
%%{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 平台包＋功能插件"]
| 階段 | 內容 | 工作量 | 進度 |
|---|---|---|---|
| 第一階段 | 抽五支新套件＋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 分家＝複用前提。決策全文見專案平台化決策頁 |
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 儀表板框架（收尾棒） | ⬜ 排最後 |
完全體 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。半體升完全體的門檻（身分脈絡名冊、流程疆界）都排在第四階段。
這節在講什麼：每一支套件從哪裡來、最後變成什麼。 FR-069 四階段已於 2026-09-01 全數收口， 本節即終態，不再是滾動快照。
怎麼數才對：本 arc 期間曾同時存在的套件目錄共 26 支（含過渡目錄名與待退役者）。 收口後 現役 25 支（＝磁碟目錄數＝主專案 pyproject.toml pin 數，兩者實查相符）， 退役刪除 10 支／塊。25 + 10 ≠ 26 是因為多數退役者是被合併而非憑空消失 （四支身分套件合成 1 支、兩支改名不算新增）。
| 套件 | 版號 | 從什麼變成什麼 | 形態 |
|---|---|---|---|
| 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）。
| 刪掉的 | 去向 / 為什麼 |
|---|---|
| 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 變成假綠。
拆完之後「我們的產品還剩什麼」是最常被問的問題。答案是四類，每一類都只有這個產品有 ——換第二個產品，這四類要重寫，但 25 支積木照裝。
| 類別 | 這是什麼 | 為什麼不拆 | 實例 |
|---|---|---|---|
| ① 報表櫃檯（readmodel） | 跨疆界的純讀聚合：一張畫面要同時顯示任務＋專案名＋控制項＋稽核輪狀態 | 「要並排顯示什麼」是這個產品的設計決定，換產品欄位就換一套。各檔口賣自己的菜，套餐由櫃檯出 | infra/readmodel/my_grc_jobs_query.py（六疆界）、ssp_control_implementation_query.py（七疆界）、flow_control_dashboard_repo_impl.py |
| ② 接線盤（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/ |
一句話：積木是通用的，怎麼組出「Guidant AI 這個產品」是本體的事。 第二個產品＝同一批積木＋自己的櫃檯＋自己的接線＋自己的組裝。
| 時點 | 發生什麼 |
|---|---|
| 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 定調的結果。
驗收與紀律（每棒都適用）
| 項目 | 說明 |
|---|---|
| 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 等清債 |