顧問在資源庫訪談、存版、送審，專案只看不改

控制項填寫區這次只加欄位（甲案）

• 控制項表單與 AO 表單各在「備註」之後加「缺失」「缺失修改建議」兩個多行文字框。
• 「缺失修改建議」正下方加「建議附件」區塊：上傳只選檔、寫一行說明，不分種類。
• 原本的「程序書」區塊放在建議附件下方，維持原樣、分開呈現。
• 頁首加「暫存」與「儲存成新版本」兩顆鈕，以及「版本歷史」入口。
• 其他七個頁籤不動。

理由：先讓顧問能把缺失寫進正確欄位，重新設計填寫區等全部做完、實際用過再看。ModuleFrameTemplateEditView.vue 已 2,246 行，新增的欄位與建議附件區塊一律做成新子元件掛進去。

✅ D1 — 缺失與缺失修改建議存 OSCAL props

定案：新增兩個 props 鍵（gap、recommendation，帶自家 ns），控制項與 AO 兩層都有。不加實體欄、不開側表、不寫 POA&M。

理由：與既有「實施狀態」「現況說明」走同一條路；啟動專案、稽核凍結、存版都是整列複製，props 自動帶走；OSCAL 標準允許自訂 props。

被排除：套件加實體欄（OSCAL 標準沒有這欄，還要動 schema）；主專案側表（每條複製路徑都要手動補，程序書池就曾因此漏帶）；直接寫評估結果或 POA&M（啟動稽核才會生成，資源庫階段沒有容器可放）。

✅ D2 — 「備註」就是既有 remarks

定案：不新增欄位。

理由：兩表本來就有 remarks；資源庫 AO 有在用，只是專案規劃頁控制項存檔沒送（ProjectPlanningView.vue:1443），改唯讀後這個漏洞自然消失。

✅ D3 — 建議附件獨立一張表，不進程序書池

定案：顧問附在建議下面的檔案存新表 compliance.ssp_control_attachments（context_type 為 control_implementation／objective，加 context_id、file_id→upload_files、description、審計欄）。程序書池不動、不加文件種類欄，jedi-compliance-audit 套件不改。版本存版、還原、複製資源庫時這張表跟著複製；稽核凍結不帶。畫面放在「缺失修改建議」正下方，區塊名「建議附件」，與下方「程序書」分開。不分類，只有檔案加一行說明（D15）。AO 層 props 裡舊的 reference-documents JSON 不碰。

理由：程序書是客戶自己的 SOP，用來證明現況，要進稽核凍結；顧問附件是建議的一部分，客戶照著做完就沒用了，不該混進稽核基準。兩者若同池、靠種類欄過濾，稽核側每個讀程序書的地方都要多一個條件，漏一處就讓建議範本跑進稽核。

被排除：程序書池加「文件種類」欄（稽核側讀取處要逐一加過濾，且要改套件）；用檔名或描述欄約定（查不了、篩不了）。

✅ D4 — 訪談表兩條路徑都加三欄，docx 不動

定案：路徑 A（完整匯入）與路徑 B（控制項現況九欄）的欄位定義都加「備註」「缺失」「缺失修改建議」；匯出同步帶出。docx 匯入不動。

理由：訪談表就是現況資料 Excel，顧問在現場直接填；兩條路徑共用欄名定義，只改一處會造成兩份表欄位不一致。docx 是另一種來源，不在顧問訪談流程內。

✅ D5 — 四個坑全收

定案：

1. 套件 update 模式的 props 改成逐鍵合併：檔案裡有的鍵才蓋，沒有的鍵保留。
2. 資源庫完整匯入改用合併語意，不清空重建，讓多次匯入可以累積。
3. 實施狀態值域收進 system_menus 當唯一來源（六值，拼法見 D20），FE、Excel 驗證、BE 驗證都讀它。
4. props 讀寫 helper 收成一支共用，匯出、差異比對、合併決策同步認得新鍵。

理由：不修①②，顧問第二次匯入只填了缺失欄，上次的現況說明就被清掉——這正是「多次匯入累積」的反面。不修③，三處各自一組值，新欄位上線後下拉、匯入、匯出會各說各話。不修④，新鍵要改六個地方，漏一處就是某條路徑看不到缺失。

✅ D6 — 有資源庫編輯權的人都能編範本 SSP

定案：拿掉「只有帳號層超級管理員能寫範本 SSP」的守門（common/authz/ssp.py:215），改成具備資源庫編輯權限即可。「顧問」角色之後再定義。這條守門目前其實走不到（雙模式解析器沒接上，見盤點 ④），所以實作是「在範本 SSP 的所有寫入入口要求資源庫編輯權」，不是改一行判斷。

理由：顧問是主要編輯者，現行守門是開發期的暫時做法（註解自己寫著「dev-stage gate」）。

被排除：先建「顧問」角色再開權限（角色定義牽涉授權模型，會卡住整案）。

✅ D7 — 專案規劃頁唯讀，編輯權只在資源庫

定案：專案規劃頁上，資源庫帶來的資料除任務設定外全部唯讀。任務設定（指派、到期日、說明）照舊可編、不動；唯讀的是控制項與 AO 實施層欄位、程序書、建議附件、其他 SSP 頁籤。FE 的可編判斷與 BE 專案側 SSP 寫入守門一起改。

理由：客戶專案管理者只指派工作與上傳證據；SSP 是顧問的工作成果，兩邊都能改就會互相覆蓋。

✅ D8 — 資源庫與專案一對一，啟動不再複製 SSP

定案：

• 啟動專案時專案直接指向資源庫的範本 SSP（living_ssp_id＝template_ssp_id），不再複製三件組。
• 啟動時擋「這個資源庫已經有進行中的專案」。
• 資源庫有專案綁著不能刪。
• 新年度走「複製資源庫」產生新資源庫，程序書池、建議附件與表單設定要帶過去，版本歷史不帶。做法見 D17。
• 資源庫沒有公版。公版是框架層（framework／catalog）的概念；module_frames.scope 欄位保留不拆，概念預留但預設不開放使用者，畫面不出現公版資源庫。顧問從框架層選控制集，自建、自維護資源庫。

卡 8 硬性前置：runner 動手前先逐項盤點 app/project/service/project_start_app_service.py 的複製鏈（三件組、程序書池、ssp_risks、控制項初始化 :385-389），分成三類列出——「啟動專案要留的」「搬去複製資源庫的」「當初順手塞進來的」——回報後才動。這段程式本身寫得亂，不盤點直接改，容易把該留的一起拿掉。

理由：顧問啟動專案後仍持續訪談，只有指向同一份，專案才能即時看到；複製一份就得再設計「資源庫改了怎麼同步到專案」，那是兩份真相。

被排除：維持複製、另做同步（雙向衝突與同步時機都要另外設計）；一個資源庫多個專案共用一份 SSP（不同客戶的現況會互相覆蓋）；資源庫層加「公版」旗標（公版屬框架層，資源庫層再做一套是兩份概念）。

✅ D9 — 送審即鎖版，稽核中資源庫鎖寫

定案：「送審」就是現在的「啟動稽核」。按下時依序做「存版→鎖版→凍結→鎖寫」：存一版進版本索引（source='submit'，audit_round_id 記對應稽核輪），照舊凍結快照給稽核輪，資源庫進入鎖寫。輪次進入整改（remediation）就解鎖（D19）。覆核輪（close_out）送審走同一套，不做特例；覆核送審時再鎖一次。版本歷史與稽核輪靠 audit_round_id 互指，三層關係見資料模型「三層關係」表。稽核流程本身不改。

理由：外部稽核看的是送審那一刻的內容，顧問要能回頭看「送審時寫了什麼」；主稽核與覆核各對應哪一版，要能從兩頭查到。

被排除：稽核中仍允許改工作副本——專案規劃頁直接指向工作副本，客戶專案管理者會看到規劃頁與稽核中的內容不一致；覆核另做一套（兩套鎖版規則容易走歪）。

✅ D10 — 版本走 OSCAL 原生欄位＋一張索引表

定案：版號與修訂史寫 OSCAL 原生 metadata.version 與 metadata.revisions（每筆 revision 的 links 帶 rel=predecessor-version 指前一版 uuid）；舊版內容用套件 snapshot_ssp 整份複製成獨立 SSP；版本這件事只多一張索引表，設計成「SSP 的版本」（owner_type＋owner_id），第一版只有資源庫用。OSCAL 各表不加任何版本欄。

理由：OSCAL 本來就有版本與修訂史欄位，匯出的 SSP 自帶版本資訊；整份 SSP 快照讓看舊版、比對、還原都能直接用既有的編輯器與 diff，不用多一層轉換。

被排除：只寫 metadata（做不到回顧、比對、還原）；存 JSON 文件快照（還原要走匯入路徑，匯入的坑沒修之前不可靠；看舊版與比對都要多一層轉換）；在 SSP 主表加 group_id／version_no（早期 FR-019 的做法，v2 已移除）。

✅ D11 — 版本操作的範圍

定案：

• 版本快照是整份 SSP：主表、12 子表、程序書池掛載、建議附件、風險。
• 暫存不開版；儲存成新版本先暫存再快照；匯入確認成功自動存一版；版本歷史列表；唯讀開舊版（既有編輯器加唯讀旗標）。
• 比對接既有 diff 的「SSP 對 SSP」入口，第一版只比控制項與 AO 的實施層欄位：狀態、現況、備註、缺失、建議、程序書掛載、建議附件。其他頁籤不比。
• 還原＝整份換回去，不做逐項。按下先列「會改動：控制項 N 條、負責單位 M 筆……」給顧問確認；確定後把舊工作副本自動存成一版（pre_restore），再把那一版複製成新工作副本並換指向，所以永遠可逆。
• 稽核凍結快照不進索引表。

理由：顧問在乎的是控制項層的內容變化，比對先做這一層，避免範圍膨脹；還原逐項挑會讓「還原後的工作副本」變成哪一版都不是，整份換加上確認清單，顧問知道會動到哪些頁籤。

✅ D12 — 控制項填寫區這次只加欄位

定案：甲案——控制項與 AO 表單各加兩個文字框，建議下方加「建議附件」區塊。重新設計留到全部做完再看。BE 照樣做「整條控制項連 AO 批次存」API，給暫存用。

理由：先讓資料有地方放，畫面改版等顧問實際用過再決定。

✅ D13 — 範本 460 的缺失回填另開小卡

定案：FR-138 在範本 460 塞進「現況說明」的缺失，新欄位上線後開一張小卡，人工或半自動拆到「缺失」欄。

理由：460 是第一個真實使用者案例，拆完正好驗證新欄位與缺失報告的需求。

✅ D14 — props 的 ns 與 name

定案：ns＝https://guidant.ai/ns/oscal，name＝gap、recommendation。全產品之後的自訂 props 都用同一個 ns。

理由：OSCAL 規定自訂 props 帶自家 ns，避免與標準名稱撞；全產品一個 ns，之後不必再為每個欄位另想。

✅ D15 — 建議附件不分類

定案：建議附件只有檔案加一行說明，不分種類、不進 system_menus。

理由：建議附件與程序書已經分表（D3），種類的作用已由「放在哪張表」承擔，再分類沒有讀取端要用。

✅ D16 — 兩張新表的 schema 與名稱

定案：compliance.ssp_versions（版本索引）、compliance.ssp_control_attachments（建議附件）。判準是「model 寫在哪個套件就放那個 schema」——兩張 model 都在主專案，放 compliance。跨 schema FK 指 oscal.system_security_plans 是正常的，先例 project_audit_rounds。

理由：放 oscal 會讓人以為是 jedi-oscal-v2 套件的表；schema 跟著 model 歸屬走，查表時不必猜誰管。

✅ D17 — 複製資源庫走搬家，不另寫

定案：把啟動專案現有的複製邏輯（套件 clone_resource_library 複製三件組，加程序書池、表單設定、ssp_risks）搬成「複製資源庫」，再補帶建議附件。啟動專案不再用它。不做公版旗標，module_frames.scope 欄位留著（D8）。搬之前照 D8 的卡 8 前置先盤點。

理由：複製路徑與現在的啟動專案幾乎相同，搬過來等於重用；匯出 Excel 再匯入帶不走程序書檔，也依賴匯入坑修完。

被排除：匯出再匯入；資源庫加公版旗標（公版屬框架層，D8）。

✅ D18 — 「有資源庫編輯權」＝oscal.resource-library.update

定案：沿用 oscal.resource-library.update（目前 51 處使用，資源庫寫入端點已全用它），不另立新能力點。範本 SSP 的所有寫入入口都要求此能力點，包含坑 2 提到的 SSP 共用端點：這些端點依「此 SSP 是否為某資源庫的 template_ssp_id」分流，是就走資源庫守門（此能力點＋稽核中鎖寫），不是才走專案守門。之後定義「顧問」角色時把這個能力點配進去即可。

理由：只守資源庫自己的端點，客戶專案管理者仍能從共用端點改到顧問的 SSP（坑 2、坑 6）。

✅ D19 — 輪次進整改就解鎖

定案：輪次進入整改（remediation）資源庫就解鎖，不必等結案；覆核送審時再鎖（D9）。

理由：顧問在整改期正好要邊訪談、邊更新現況與建議；稽核基準已凍結在稽核輪自己的快照，改工作副本不影響稽核結果。

✅ D20 — 實施狀態保留底線拼法、多收 unknown

定案：key 保留底線 not_applicable，OSCAL 五值之外多收 unknown（＝還沒訪談），共六值：implemented／partial／planned／alternative／not_applicable／unknown。值域進 system_menus group ssp_implementation_status，FE 下拉、Excel 匯入驗證、BE 驗證三處讀同一份。匯出 OSCAL 時才轉成標準拼法 not-applicable。

理由：DEV 現存 implemented 70,914、unknown 2,133、partial 47、not_applicable 13、alternative 2、planned 2；底線拼法已散在讀取端與七萬多筆資料裡（ssp_control_implementation_service.py:42 的註解即依賴它），硬改風險大而對使用者沒有可見收益。unknown 是真實狀態，顧問需要。

被排除：key 對齊 OSCAL 連字號並 migration 改既有資料（要找出所有依賴底線拼法的讀取端，unknown 也無處可去）。

✅ D21 — 既有資料不搬，只對新啟動專案生效

定案：既有「一資源庫多專案」的舊模式專案不遷移，維持各自獨立的 SSP 副本，照舊在專案側可寫（守門依「專案 SSP 是否就是某資源庫的 template_ssp_id」分流）；一對一檢查只算新模式專案。STG／POC 上線前檢查有無一資源庫多專案，列進上版檢查項。

理由：DEV 實況資源庫 460 綁 3 個專案、427 綁 1 個，全部是舊的「複製一份」模式；遷移要決定哪個專案接手範本 SSP，對既有客戶的稽核輪沒有收益。