定版參考文件 · 只寫現況 · 已出貨
這頁是 FR-080 的定版交付規格——只回答「現在長什麼樣」。要看「當初為什麼這樣決定」去 design.md，要看「哪一棒做了什麼」去 handoff/LOG。本頁不記沿革、不 append 進度，內容變了就整段改寫。
25 支套件合併成 21 支，分五層，上層可以用下層、下層不准反過來認識上層。 被合併掉的六支搬進 archive/ 封存，不刪也不再發版。
主專案要接一支套件，就在 core/plugins/ 下開一個同名檔案接它——裝上、接好線、API 就自己長出來，主專案不用重寫一次業務邏輯。
版號為 Nexus 上的現役版本。「自帶 SQL」是套件 migrations/ 目錄下的腳本支數——有值代表該套件自己帶資料表，客戶端升級鏈由 FR-093 負責。
| 套件 | 做什麼（一句白話） | 層 | 版本 | 自帶 SQL |
|---|---|---|---|---|
| jedi-common | 地基：資料庫連線、交易、錯誤格式、共用工具。所有套件都踩在它上面 | ① 基座 | 1.0.1 | — |
| jedi-iam | 登入、帳號、角色、租戶、權限。管「你是誰、能不能進來、能做什麼」 | ② 中介 | 1.0.1 | — |
| jedi-log | 日誌管線：API 存取紀錄 ＋ 轉發到客戶 SIEM（syslog／GELF，選配、可失敗） | ② 中介 | 1.0.1 | — |
| jedi-integrity | 防篡改：開機前逐檔比對簽章，程式被改過就拒絕啟動 | ② 中介 | 1.0.1 | 1 |
| jedi-license-runtime | 授權驗證：讀客戶的授權檔、驗簽、到期狀態機、開通與展延 | ② 中介 | 1.0.1 | 3 |
| jedi-notification | 寄通知：Email、Discord、Telegram 三個出站管道 | ③ 平台服務 | 1.0.1 | — |
| jedi-file-upload | 檔案上傳下載、轉 PDF 預覽，支援本機與 S3 類儲存 | ③ 平台服務 | 1.0.1 | 2 |
| jedi-system-core | 系統開機字典：系統設定表（SMTP、LDAP、儲存設定）＋ 前端下拉選單字典 | ③ 平台服務 | 1.0.1 | 2 |
| jedi-asset | 資產清冊：設備（主機、IP、OS）＋ 資訊系統（FIPS-199 等級、系統狀態、負責人） | ③ 平台服務 | 1.0.1 | 2 |
| jedi-bulletin | 系統公告：發布、到期、發給哪些部門 | ③ 平台服務 | 1.0.1 | 2 |
| jedi-issue | 工單與意見回饋：本地工單，可同步到 GitLab／GitHub | ③ 平台服務 | 1.0.1 | — |
| jedi-remote-agent | 客戶端 agent 的註冊、心跳、派工、mTLS 身分。是通道，不含業務 | ③ 平台服務 | 1.0.1 | 3 |
| jedi-ai-bot | 系統內建 AI 聊天視窗 | ③ 平台服務 | 1.0.1 | — |
| jedi-ai-dashboard | 一句話生成儀表板：AI 挑資料源、查資料、設計版面 | ③ 平台服務 | 1.0.1 | — |
| jedi-task-platform | 專案與任務骨架：專案主檔、任務留言、任務綁設備／組織／問卷、匯入匯出，加上誰被指派到哪一層與角色繼承 | ③.5 骨架 | 1.0.1 | 2 |
| jedi-flow-engine | BPMN 流程引擎：解析流程圖、推進節點、記錄執行 | ③.5 骨架 | 1.0.1 | — |
| jedi-oscal-v2 | OSCAL 合規標準資料模型：控制項目錄、基準線、SSP、評估計畫與結果、改善計畫，共 45 張表 | ④ 業務 | 2.3.1 | — |
| jedi-compliance-audit | 稽核業務本身：稽核輪次七態狀態機、評估計畫與結果匯入、缺失追蹤、審閱標記 | ④ 業務 | 1.0.1 | — |
| jedi-survey | 問卷：設計問卷、發給人填、記錄作答與修改歷史、多人即時共編 | ④ 業務 | 1.0.1 | — |
| jedi-detection | 檢測：檢測工具目錄、租戶憑證、檢測基準庫、派工到 agent、收回掃描報告 | ④ 業務 | 1.0.1 | 2 |
| jedi-evidence-classification | AI 證據分類：把 Google Drive 上的證據檔用 AI 對應到評估項目 | ④ 業務 | 1.0.1 | 2 |
粗體四支是合併產物，其餘 17 支維持原樣。
| 合併後 | 由誰組成 | 合併的判準 |
|---|---|---|
| jedi-asset | jedi-device ＋ jedi-information-system | 同一件事的兩種型別（資產清冊表本來就用 asset_type ∈ {hardware, information_system} 區分） |
| jedi-task-platform | jedi-task-platform ＋ jedi-participant | 資料同生共死（任務指派 12,479 筆全部對得上專案表），且是整個套件庫唯一的雙向循環 |
| jedi-system-core | jedi-system-config ＋ jedi-system-menu | 同層、同性質（字典型增刪改查）、近三個月三次同批異動 |
| jedi-log | jedi-log ＋ jedi-log-forwarding | 同屬中介層，「記錄」與「轉發」是同一條日誌管線的上下游 |
被合併的六支（device、information-system、participant、system-config、system-menu、log-forwarding）已搬到 jedi-python-package/archive/——不刪、不發版、不再維護。
這三組看起來該合，刻意保留分開。列在這裡是為了不要每次有人看到就再問一次。
| 這兩支 | 為什麼不併 |
|---|---|
| oscal-v2 與 compliance-audit | oscal-v2 是國際合規標準的資料模型，任何合規產品都可能用；compliance-audit 是本產品獨有的七態流程。合了等於把通用標準庫綁死在 Guidant 的狀態機上 |
| integrity 與 license-runtime | 資料完全不共用、啟動時機不同（一個在服務起來之前跑、一個在之後）。共用的只有簽章驗證引擎 |
| detection 與 remote-agent | 一個是業務層、一個是平台服務層。remote-agent 是通道，通道不能併進業務 |
① 基座 jedi-common
↑
② 中介層 jedi-iam ／ jedi-log ／ jedi-integrity ／ jedi-license-runtime
↑
③ 平台服務 notification ／ file-upload ／ system-core ／ asset ／ bulletin
issue ／ remote-agent ／ ai-bot ／ ai-dashboard
↑
③.5 骨架 jedi-task-platform ／ jedi-flow-engine
↑
④ 業務 oscal-v2 ／ compliance-audit ／ survey ／ detection
evidence-classification規則三句：上層可以用下層；下層不准反過來認識上層；同一層之間也不准直接互相抓，要合作就經過主專案轉一手。
這三條不是靠自律——守衛測試 test/test_module_boundaries.py 會擋，寫錯就測試紅字。
判某支該歸哪層用兩個問題：壞了會怎樣（基座壞了全倒、業務壞了只倒一塊）、換一個產品還要不要（要 → 越下層）。長期規範版見 架構手冊的套件分層頁。
要開一個新產品，裝這五支就有登入、存取紀錄、設定、選單、寄信：
jedi-common ＋ jedi-iam ＋ jedi-log ＋ jedi-system-core ＋ jedi-notification其餘依產品需要選裝。
🔴 一個陷阱：system-core 的表結構屬於套件沒問題，但它裡面那 74 筆下拉選單資料含有稽核專用的項目（像「稽核方法」「SSP 角色」）。表跟著套件走，資料留在主專案——不然新產品裝上去會冒出一堆稽核才有的選項。
一支套件一個檔：core/plugins/<pkg>.py。檔案裡固定三段——① 回答套件開出來的問題（它問「誰是這個使用者」，主專案答）、② 填一張表把答案交給它、③ 把 API 掛上去。接手的人一個檔看完，不用翻五個地方。
接一支新套件只要三步：
pyproject.toml 加一行相依core/plugins/<pkg>.py，照抄任一支現成的core/plugins/__init__.py 的 PLUGINS 清單加一列第四步只有在「主專案別的地方要直接用這支套件的服務」時才做（di_containers/ 加一顆）。純掛 API 不需要。
🔴 PLUGINS 的順序就是掛載順序，沒理由不要重排。兩處有實質依賴：identity 必須早於 file_upload；api_log 必須晚於 configure_logging()。
詳細機制（袋子比喻、guards.py、port 與 adapter、一個 request 的旅程）見 FR-089 插件解剖；不需要技術背景的版本見 給 PM 的說明。
指令：python scripts/deliverables/plugin_metrics.py（BE repo 根目錄跑）。
| 量什麼 | 白話 | 開工前 | 現在 |
|---|---|---|---|
| 套件之間直接抓對方程式的地方 | 越少越好。這種線換到別的產品就會斷 | 120 處 | 93 處 |
| 開了接口但沒人用 | 宣告了「我需要你給我這個」卻沒人接，是白宣告 | 16 個 | 4 個 |
| 主專案接線的程式行數 | 接線是主專案回答套件「你要的東西我給你」的那份程式 | 7,457 行 | 9,762 行 |
| 裝上就能用、不用改主專案的套件 | 越多越好，這是「隨插即用」的直接量測 | 17 支 | 17 支 |
兩個數字要解釋一下，不然會看成變糟：
⚠️ 指標工具目前回報 infra/detection_tools/adapters.py 找不到（檔案已搬走），接線行數會少算，待修清單。
寫在這裡是為了不要被當成已完成。每一項都有人接，接的是哪個案子見下一節。
| 沒做完的事 | 白話說明 | 誰接 |
|---|---|---|
| 🔴 切子租戶功能暫不可對外 | 有 13 張表沒把「每個客戶只看自己資料」這道鎖打開，切到子租戶會看到別人的東西 | FR-094 |
| flow-engine 沒補實 | 流程引擎的核心程式被複製到主專案改過，現在套件裡那份 549 行沒人用、主專案那份 1,559 行才是真的在跑。兩份已經長歪，方法簽名都對不上 | CM-1478 流程疆界設計（未開工） |
| 主專案 DI 瘦身 | 主專案有 48 處直接去綁套件內部的元件，應該改成跟套件要（host_services()） |
已完成（FR-090 第 6 棒） |
| 套件自帶的資料表建不起來 | 套件會帶自己的建表腳本，但出貨的安裝程式只讀主專案那份，客戶升級時套件的表永遠不會出現 | FR-093 |
| 主體還沒進版 1.20.0 | 21 支套件都出版了，主專案本身還沒 | FR-089（等令） |
| 指標工具有一條失效路徑 | plugin_metrics.py 指著一個已經搬走的檔，導致接線行數少算。工具自己會印 FAIL |
已修（2026-09-16） |
FR-080 只做「合併成 21 支」。做完之後陸續長出六個案子，都是這一輪的直接後果。要判斷「套件這條線現在到哪」，看這張表。
| FR | 在做什麼（白話） | 為什麼會長出來 | 狀態 |
|---|---|---|---|
| FR-089 | 21 支套件長相統一 — 每支的檔案怎麼擺、API 怎麼拆、logger 怎麼掛，全部照同一套 | 合併完發現 21 支各長各的，接手的人每支都要重學一次 | 🟢 全案 Done，套件 1.0.1 已出版；剩主體進版 |
| FR-090 | 主專案側殘留清理 — 功能搬進套件後，主專案留下的空殼、轉接層收乾淨 | 功能上移了，舊的那份沒人刪 | 🟢 七棒 Done，含 DI 瘦身三卡（CM-1749～1751） |
| FR-091 | 把 FR-089 定的形狀真的套到 21 支 | FR-089 定規格，FR-091 是施工 | 🟢 28 卡全 Done |
| FR-092 | 廢碼清理 — 搬完之後沒人引用的檔案、沒人打的 API 端點刪掉 | 三輪搬移累積下來的殘骸 | ✅ 全案收口 |
| FR-093 | 出貨升級鏈補齊 — 讓套件自帶的資料表、權限、選單在客戶升級時自動到位 | 查出出貨安裝程式只讀主專案的建表腳本，套件那份客戶端永遠套不到 | 🟡 進行中（母卡 CM-1752，十棒） |
| FR-094 | 租戶隔離修正 — 13 張表＋4 支 view 真的把「每個客戶只看自己資料」關上 | 資產套件補鎖時連帶盤出一整批沒關的 | 🟡 已開卡待派（母卡 CM-1766，八棒） |
另有一條盤點性質的：FR-087 租戶隔離破洞盤點（✅ 已盤完）——它只查不修，查出來的東西交給 FR-094 動手。
這條線的閱讀順序：先看本頁知道合併結果 → FR-089 知道套件長什麼樣 → FR-093／094 知道還有什麼沒好。
| 你想知道 | 看哪份 |
|---|---|
| 現在長什麼樣（21 支、五層、誰依賴誰、怎麼接） | 本頁 |
| 當初為什麼這樣決定、被推翻過什麼 | design.md |
| 哪一棒做了什麼、驗收結果 | handoff/fr080-LOG.md |
| 原始盤點證據（25 支逐支 8 題、宿主接線、空殼細查） | inventory/ |
| 套件這條線現在整體到哪（六個後續案子的狀態） | 本頁的延伸 FR 段 |
| 一支套件內部長什麼樣（檔案怎麼擺、守門怎麼寫） | FR-089 插件解剖 |
| 長期的分層判準（以後照這個判） | 架構手冊 · 套件分層 |