jedi-* 套件整併與服務化路線：25 支收成 21 支，每支可分開部署、預設兩支分開跑

兩軸總覽（25 → 21）

五個結論

1. 分類要用兩把尺，且證據要看內容不看形狀。第一把是子領域型態（地基／通用／核心），第二把是部署剖面（函式庫／進程內／分開部署）。前六輪推演用行數、表數、grep 計數、pyproject 宣告判合併，四組合併案（system-infra 五合一、asset、detection 吞 remote-agent、ai 三合一）全部在讀了 README 疆界、表欄位、port、消費者用途後被推翻。手冊 D17 律①「想建外鍵＝該住一起」才是合併的唯一判準：程式碼耦合可用 port 解，資料耦合不行。
2. 25 支收成 21 支，四組合併：前三組以「表是否互掛外鍵、是否天天連表」為判準：① 任務平台——task-platform 吞 participant（六張參與者表全掛在任務表上，ORM 直接 relationship，兩包雙向 import）；② 系統字典——system-config＋system-menu（兩張 group/key/value 表、同一群人維護、零 port 使用）；③ 日誌——jedi-log 收下 common 的 system_logs，log-forwarding 為 sink 子模組（兩張表都是產品自產紀錄，LogTypeCode 早預留 SYSTEM_LOG=2）；④ 資產——device＋information-system 合為 jedi-asset（決策者裁定：兩支同為資產盤點清冊、同一群人維護、都是半體，合併一次升完全體；欄位不重疊不構成拆開的理由，一支資產套件內含兩種資產型別是自然的）。flow-engine 不併（決策者 2026-09-09 拍板選 B，維持 FR-069 D-10）。其餘 15 支各自疆界站得住，不動。
3. 今天零支是服務。FR-069 做的是模組化不是服務化：全部在同一進程、同一 DB、同一 transaction；零 broker、零 outbox；10 支有真獨立 harness 但沒有進 CI。
4. 「可分開部署」是設計要求，「預設分開部署」是部署選擇。七階補完後，除 5 支函式庫外的 16 支都要能用 import 模式或 API gateway 模式跑，套件碼一行不改；但今天只有 detection 與 evidence-classification 有分開跑的收益。iam、survey 技術上都能分開部署，只是要等觸發條件。
5. 前三階（harness 進 CI、契約層、資料解耦）約 20 棒完成插件模式，達成「其他專案隨插即用」；第 3 階收完停下評估第二個產品是否出現，再決定後四階（身分可攜、outbox worker、雙 adapter、detection 切出）。

下一步：第 0 階套件合併，順序 資產（最小、零 migration、決策者指定首棒）→ 系統字典 → 日誌 → 任務平台吞 participant。每組比照 FR-069 退役慣例（死名守衛、移出 EXTRACTED_PACKAGES、pin 改名、Nexus 發版等令）。

兩把尺

合併的三個條件（全部成立才合）

1. 另一個產品會整包要它：切到「一個業務能力」為止，不切到「一張表」。1 千行、1 張表的套件單獨存在是 nanoservice。
2. 資料自己擁有：有 FK、天天 JOIN 的表必須同單位；跨單位只留軟參照。
3. 沒有任何人受害：同操作者、同生命週期、彼此零 import 或單向 import。

「可分開部署」與「預設分開部署」是兩件事

%%{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 TB
  subgraph L5["⑤ 領域積木（GRC 專屬，挑用或換掉）"]
    OSCAL["jedi-oscal-v2<br/>函式庫"]
    AUDIT["jedi-compliance-audit"]
    SURVEY["jedi-survey"]
    DET["jedi-detection"]
    EVID["jedi-evidence-classification"]
    DASH["jedi-ai-dashboard"]
    BOT["jedi-ai-bot"]
    ISSUE["jedi-issue"]
    ASSET["jedi-asset<br/>★ device＋information-system"]
    BULL["jedi-bulletin"]
  end
  subgraph L4["④ 平台核心（插座）"]
    TASK["jedi-task-platform<br/>★ 吞 participant"]
    FLOW["jedi-flow-engine<br/>函式庫（不併）"]
  end
  subgraph L3["③ 安全與部署"]
    IAM["jedi-iam"]
    LIC["jedi-license-runtime"]
    INTEG["jedi-integrity<br/>函式庫"]
    FILE["jedi-file-upload"]
    RA["jedi-remote-agent"]
  end
  subgraph L2["② 系統基礎建設"]
    DICT["jedi-system-dict<br/>★ config＋menu"]
    LOG["jedi-log<br/>★ api_logs＋system_logs＋forwarding"]
    NOTIF["jedi-notification"]
  end
  L1["① 地基　jedi-common（★ system_logs 搬走）"]
  L5 --> L4 --> L3 --> L2 --> L1

總表

四組合併的證據與被推翻的三組

四組合併，各自的證據：

命名：系統字典套件暫名 jedi-system-dict，替代 jedi-system-config（沿用其中一支的名字，menu 併入）。日誌套件沿用 jedi-log（dist 名）但 import 名 jedi_api_log 要改回 jedi_log，因為它不再只是 api log。

今天實際的部署形狀

真正以獨立進程跑的東西都不是 jedi-* 套件：RUN_MODE=socketio（同 image 的傳輸分身）、License Center（獨立 repo，license-runtime 是它的客戶端）、客戶主機上的 agent 執行檔（remote-agent 是伺服端）、SeaweedFS／Postgres／Redis（基礎設施）。

脫離宿主啟動的能力：harness 三級

harness 是每支套件自帶的最小獨立宿主（harness/dev_app.py ＋ docker-compose.yml）：起一個空 Flask app、連自己的空 DB、register() 掛上、宿主該給的 port 用 Fake 頂替、test_client 實打 route。它證明零隱藏耦合——比 grep 守衛強一級，因為對空庫跑，SQL 字串裡偷 JOIN 宿主表會直接炸。FR-069 D7 列為標配。

有 Flask 殼就能做事嗎：差四樣

harness 只證明「活著」，離「有用」差四樣，每樣對應七階中的一階：

決策者要的效果拆成三個目標，需要的深度不同。A、B 是插件模式，C 是微服務模式；A 不需要等 C。

%%{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 TB
  S0["第 0 階　套件合併 25→21"]
  subgraph PLUGIN["插件模式（目標 A、B）"]
    S1["第 1 階　harness 全面 A 級 ＋ 進 CI"]
    S2["第 2 階　port 收斂成契約層 jedi-contracts"]
    S3["第 3 階　資料層解耦 ＋ 宿主範本"]
  end
  EVAL{"評估點：第二個產品<br/>來了嗎？要哪幾支？"}
  subgraph MICRO["微服務模式（目標 C）"]
    S4["第 4 階　身分可攜（claims 進 token）"]
    S5["第 5 階　Postgres outbox ＋ RUN_MODE=worker"]
    S6["第 6 階　雙 adapter ＋ 宿主薄連接器"]
    S7["第 7 階　detection 第一刀"]
  end
  S0 --> S1 --> S2 --> S3 --> EVAL
  EVAL -->|要| S4 --> S5 --> S6 --> S7
  EVAL -->|不要／未定| STOP["停在插件模式<br/>已達成隨插即用"]

工作量：第 0～3 階約 20 棒達成「隨插即用」；第 4～7 階約 10 棒。第 3 階收完停下評估——那時才知道第二個產品來不來、要哪幾支。

每支套件的部署地位

iam 與 survey 怎麼分開部署

兩種模式的實作形式

契約層 jedi-contracts
  IProjectDirectory（Protocol）
       ↑ 實作 A                       ↑ 實作 B
  InProcProjectDirectory           HttpProjectDirectory
  （直接 call task-platform）      （打 gateway /api/projects/{uid}）

宿主接線：UNIT_MODE_survey=inproc | remote

• import 模式：pip install jedi-survey，register() 掛 route，port 注入實作 A。今天的樣子。
• gateway 模式：survey 跑自己的容器，gateway（落地版用已在 stack 裡的 Traefik／nginx）把 /api/survey/* 路由過去；宿主只裝 connector 申報，port 注入實作 B。
• 套件碼一行不改，它只認 Protocol。

預設部署的容器

從三個容器變七個。一個模組化單體帶三個分身，加兩個真服務，加一個外部簽發系統，是這個團隊規模與產品形態下的合理上限。

觸發條件

第一欄是本檔已定案的事（現在就是這樣），第二欄是什麼情況要重議，第三欄是重議後會變成什麼。這張表不是待辦清單。

規模與跨套件 import

跨套件 FK 與 pyproject 相依

執行期事實

• jedi_iam/middleware/jwt_mw.py 每 request 呼叫 user_service 查 DB 建 UserContextDTO；JWT 只帶 identity=user_uid（login_service.py:132）
• api_logs 寫入點在主專案 common/middleware/app_mw.py，同步 session.add
• 零 broker／outbox／domain event；DB 只有 config、survey 兩個 schema；30 張表有 RLS policy
• port 分兩處：jedi-common 3 支身分名冊 resolver；六支套件各自 27 支（participant 6、detection 5、compliance-audit 5、task-platform 5、survey 4、license-runtime 2）；宿主接線盤 requests.／httpx. 為零
• migration 隨包只 7 支：detection、evidence-classification、file-upload、license-runtime、log-forwarding、remote-agent、participant
• remote-agent 套件本體：detection 23 次、tool_id 13 次、scan 7 次；消費者 detection 5 處、主專案 app/remote_agent 3 處
• notification 實際內容：SMTP／Discord／Telegram 三個出站 adapter 加工廠
• 主專案 readmodel 有 22 個 JOIN 的跨疆界查詢（ssp_control_implementation_query.py），屬骨幹不隨套件走

衛生問題

• iam、file-upload、flow-engine 的 pyproject 仍宣告已退役的 jedi-auth／login／mfa／captcha
• survey、flow-engine 宣告了叫 jedi-python-package 的依賴，疑似誤填
• 主專案 infra/ 仍有 __tablename__ = "workflow_executions" 的 model，與 flow-engine 同名
• poams 在 oscal-v2 與 compliance-audit 各定義一次、roles 在 iam 與 oscal-v2 各定義一次，需確認是同表兩 ORM 還是不同 schema

四輪推演

外部 AI 分類表逐項對照

決策者提供一份外部 AI 的表並明言「只信一半」。裁決依據是實查證據，不是誰說的：

外部表完全沒碰「能不能雙模式」的門檻（port 化、軟參照、outbox、插座反向依賴）。回頭看，它的四項合併建議兩對兩錯，本檔前四輪也是——雙方都是用形狀判的，錯法一樣。

內容級盤點（第 5～6 輪，2026-09-09）

前四輪用形狀證據判斷後，決策者質疑「兩者的內容你有了解過再分類嗎」。第 5 輪派兩個 subagent 讀完 25 支的 README 疆界宣告、表欄位語意、port 設計、消費者用途、依賴方向、變動節奏，每支回答固定 7 題。結論寫進正文定案表「內容證據」欄；本節只記盤點抓到的債。

port 重複宣告（第 2 階契約層要收）

• ILicenseGuard／IProjectRoleGuard／IIdentityGuard 在 task-platform 與 compliance-audit 各一份逐字相同
• INotifier 在 iam、survey 各宣告一次，供應者都是 notification
• ISettingsReader／INotifier 樣板在 flow-engine、device、information-system 三份零使用
• IUserNameResolver 在 jedi-common 與 log-forwarding 各宣告一份同形狀

越層與反向依賴（第 3 階要解）

• compliance-audit 直接 import 22 支 oscal-v2 的 infra *_repo_impl，繞過 domain 層
• survey 的 task_surveys 對 flow-engine 與 device 做 ORM relationship，與自家 README「存 id 不建外鍵」相違
• participant → flow-engine ORM（infra/model/project_participant.py:6）；併入 task-platform 後仍是跨包 relationship

通用套件綁死產品的洩漏（各套件下次動時順手修）

participant 為什麼當初獨立、循環相依怎麼來的

• 推翻：architecture-handbook/jedi-module-map-proposal.html（09-07，未 commit）的 remote-agent 獨立與「刻意不合」理由框架
• 修正：architecture-handbook/dependency-map.md 寫「功能套件彼此零直接依賴」——第四階段後已不成立，實況見附錄 A
• 補充：architecture-handbook/package-taxonomy.md 的「同族≠同疆界」仍有效，本檔加第三個概念「同單位」
• 不推翻：architecture-handbook/project-platform-decision.md（插座 vs 插頭），是第 3 階申報制的依據
• D7 未兌現：harness 進 CI，第 1 階補
• D16 需改寫：「只准依賴 common」→「單位內自由、跨單位走契約層」，隨第 2 階改 design.md
• D6 未落實：migration 隨包只 7 支，第 3 階補齊
• D-10 維持：flow-engine 與 task-platform 兩包不合，決策者 2026-09-09 重申；本檔附錄 B 記錄了推翻它的內容證據，供日後反悔時免走回頭路
• D11 維持：device 不併檢測；device 與 information-system 合為 jedi-asset（同歸資產盤點語境，與 D11 精神一致）