事前準備資料

企業導入合規框架時，顧問會先請客戶準備手上有的資料：網路架構、組織架構、資產盤點、政策文件與程序書。顧問訪談前先看過，訪談完回來才整理 SSP。這些檔案現在走信件與雲端硬碟，系統裡沒有落點，顧問整理 SSP 時還要自己再傳一次進程序書池。

本案只做「一個能上傳的地方」，加上顧問在資源庫挑選要引用哪幾份。看過沒、留言、通知都是顧問的作業習慣，系統先不介入。

%%{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'}}}%%
sequenceDiagram
  participant A as 管理員／顧問
  participant S as 系統設定 事前準備資料大類
  participant K as 客戶
  participant P as 事前準備資料頁（公司層）
  participant L as 資源庫程序書池
  participant R as 稽核輪
  A->>S: 第一次開：帶入四個起始大類；增刪改名排序
  K->>P: 丟檔案進大類格子（不會自動進任何資源庫）
  A->>L: 從事前準備資料選用：勾選的才在這個資源庫加一列
  K->>P: 同一份資料上傳新版
  P->>L: 已引用的那列換成新版檔案
  A->>L: 移出：刪掉這個資源庫的那一列
  A->>R: 送審
  L->>R: 既有 clone 把程序書池整批複製（含已引用的列，指當時的檔案）
  K->>P: 之後再傳的不影響這次稽核

整案一句話：客戶有一頁可以把檔案丟進大類格子；大類在系統設定、跟著公司；顧問在資源庫程序書池挑選引用，選了的照大類分段出現、跟著新版更新；稽核開始時既有的程序書池複製把它們一起鎖進稽核輪。

依賴：階段二吃階段一的表；階段三吃階段二的欄位。

D9 動 jedi-compliance-audit（決策者已同意）

oscal.ssp_reference_documents 的 ORM model 與複製邏輯在套件 jedi-compliance-audit（現版 1.4.0）裡。

主專案還有另一條複製路徑：ssp_snapshot_extras 依 (file_id, description) 配對池內文件，存版、還原、複製資源庫都經過這裡，要一起補上三欄。開發期間照規範走 poetry path dependency，完成後由決策者發版。

資料表

三張新表都在 compliance schema，繼承 TenantScopedMixinModel。CREATE TABLE 必須直接帶 tenant_id 與 org_unit_id INTEGER REFERENCES public.org_units(id)。缺 org_unit_id 的話，多租戶模式下 INSERT 會 500。新表要 GRANT ... TO cm_app，sequence 也要授權。RLS 照其他 tenant-scoped 表：ENABLE＋FORCE，條件是超管或 tenant_id = ANY(app.allowed_tenant_paths)。

大類的起始值走「讀時帶入」：公司第一次讀大類時，若公司層表是空的，就從 system_menus group pre_engagement_category 複製一份進來。不在 migration 裡預先替每家公司建，新租戶建立時也不用另外掛鉤。

引用與同步規則（D6、D9）

客戶上傳事前準備資料不落任何程序書池列。只有顧問在某個資源庫選用的那幾份，才在那個資源庫的範本 SSP 程序書池各有一列。之後的同步只動「已經有的列」。

is_excluded 只代表「客戶標過時」，只由同步寫入，顧問沒有手動設定它的入口。

「可編輯」不另寫判斷，一律走範本 SSP 既有的寫入守門。common/authz/ssp.py 的 _guard_template_write 會依序做三件事：檢查 oscal.resource-library.update、呼叫 verify_template_writable（資源庫存在、不是舊版檢視、屬於本租戶）、在同一支裡檢查稽核中鎖寫（FR-139 D19：綁定專案最新一輪不是 planning 就 412）。同步服務要的是「這家公司哪些資源庫可寫」這份清單（用來決定新版、搬類、刪除要改哪些已引用的列），所以後兩步是一支不檢查能力點的判斷函式 is_template_writable，給守門與同步共用。不能另外寫一套。

同步要寫在事前準備資料 app service 的同一個 @transaction 裡，透過 domain service 呼叫程序書池服務，不直接碰程序書池的 ORM。

控制項「從程序書池選用」的候選清單排除 is_excluded=true 的列。已經掛上控制項的列被客戶標過時，掛載保留、畫面標灰，不自動拆。

選用清單的「公司」用資源庫的 tenant_id，不是登入者的：RLS 是前綴比對，總公司看得到子公司的資源庫，用登入者的會把總公司的資料列給子公司的資源庫選。

既有資料升級

既有程序書池列沒有 category_id。讀取時，沒有大類的列一律歸到這家公司 seed_key='policy' 的那個大類；那個大類被改名或刪除時，歸到排序第一的大類。不寫回填 migration。原因是既有列分散在很多租戶的很多 SSP 裡，要先等公司層大類表帶入起始值，才有值可以回填，讀時歸類比較單純。

權限（FR-160 判準：沒有「專案」對象，屬系統層）

主體域守門用 common/authz 的 capability decorator，不另立 helper。程序書池的排除與恢復沿用程序書池既有的守門 require_manager。範本 SSP 會自動走上面那條資源庫守門，不用另外加判斷。

能力點的模組前綴用 oscal，和資源庫的 oscal.resource-library.* 放在一起。DEV 目前的前綴有 ai、asset、detection、evidence、flow、grc、iam、oscal、platform、proj、survey、system、workspace，沒有 governance。

API

回應中有 created_user／updated_user 的地方要一併帶 *_name，用 common/util/audit_nickname.py 的 enrich_audit_nickname_objs。

Error code

新檔 common/code/pre_engagement_error_code.py，前綴 PRE：

新碼要同步加進 FE error-code.json，中英兩份都要。

畫面

元件照設計系統：dark-card、全站字級、hint-bar 只用在錯誤或警示。不准用左側粗色邊框。icon-only 按鈕要加 v-tooltip.top；非同步按鈕要配 loading 狀態。

| 10 程序書池改成挑選引用＋同名比對放寬（CM-3050） | 拿掉自動帶入與補齊；選用清單與選用端點；「移出」刪列與掛載；拿掉 exclusion 端點；_stem 去版次與日期尾巴＋unit test；FE 選用對話框與移出確認；清 DEV 自動帶入列 | app/pre_engagement/service/pre_engagement_pool_sync_service.py、pre_engagement_file_app_service.py、resource_library_app_service.py、ssp_document_pool_service.py、module_frame_reference_document_service.py、api/module_frame/、api/oscal/routes/ssp/ssp_document_pool_route.py；FE ModuleFrameDocumentPoolPanel.vue、document-pool/ | 卡 3、5 | 見端到端驗收第 3～9 步 |

%%{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
  C1[卡 1 資料表與大類] --> C2[卡 2 事前準備資料 BE]
  C1 --> C4[卡 4 兩頁 FE]
  C2 --> C4
  C2 --> C3[卡 3 程序書池承接]
  C3 --> C5[卡 5 程序書池 FE]
  C3 --> C6[卡 6 網路架構圖]

決策者最早看得到畫面的是卡 4（事前準備資料頁與大類頁）。卡 3 的套件改動要等決策者同意，所以排在卡 4 之後也不會擋住畫面。

1. 到系統設定「事前準備資料大類」，看到四個起始值；新增「機房與實體環境」，說明填「門禁、監控、溫濕度」；把「網路架構」改名「網路與連線」；拖曳排序。
2. 用受稽方帳號登入，側選單只有「事前準備資料」。五個格子名稱與順序和第 1 步一致，「機房」卡標題下顯示說明；頁首只有大標與公司名。
3. 在「網路與連線」丟 拓樸圖.vsdx；再丟 拓樸圖_v2_2026-10.vsdx，被問「這格已經有一份『拓樸圖』」選當成新版，看到 v2 與可展開的 v1。點名稱開預覽，看到 v2。
4. 換顧問帳號，打開 ISO 資源庫的程序書池：看不到拓樸圖。按「從事前準備資料選用」，清單照大類分段，勾拓樸圖與兩份政策文件送出；程序書池照大類出現三份、標「客戶事前準備資料」、拓樸圖是 v2。
5. 打開另一個 CMMC 資源庫，程序書池沒有這三份。ISO 資源庫綁的專案，規劃頁程序書管理唯讀、看到那三份、沒有選用與移出鈕。
6. 受稽方對拓樸圖上傳 v3，ISO 程序書池那份換成 v3。
7. 在 ISO 程序書池勾拓樸圖「當網路架構圖匯出」，匯出 OSCAL JSON 看到 network-architecture diagram。
8. 把一份政策文件掛到某條控制項，再按「移出」：跳「已掛在 1 條控制項上」，確認後池與掛載都消失。
9. 受稽方把另一份已引用的政策文件標過時：ISO 那份淡化並標「客戶已標過時」，沒有被移出；選用清單不再列出它。
10. ISO 資源庫送審。受稽方對拓樸圖上傳 v4：稽核計畫頁看到的仍是 v3；選用與移出回 412。受稽方對拓樸圖按刪除，按鈕已變成「標為過時」。
11. 對 ISO 資源庫存一版再還原，程序書池的大類、來源標籤與引用都還在。

沿革見 handoff/ LOG 與 git log。