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

狀態：設計定案（2026-10-14），待開卡｜討論稿：discussion.md｜雛形：prototype/index.html（四頁：控制項填寫、版本歷史、版本比對、專案規劃頁唯讀）

雛形是假資料畫面，欄位與選項以本文件為準（實施狀態選項以 §6.6 的六值為準）。檔案路徑與行號以 2026-10-14 為準，查不到時以函式名重新定位。路徑慣例：BE 路徑相對 compliance-manager-be/；pkg/ 代表 ~/Projects/Jedicogy/module/jedi-python-package/；FE 路徑相對 compliance-manager-fe/。

名詞：資源庫＝合規資源庫（compliance.module_frames）；範本 SSP＝資源庫底下那份 SSP（module_frames.template_ssp_id），也就是工作副本；AO＝評估目標（assessment objective），控制項底下的檢查項目；IR＝控制項實施紀錄（oscal.ssp_implemented_requirements）；props＝OSCAL 物件上的「名稱＋值」擴充屬性陣列；新模式專案＝living_ssp_id 等於某資源庫 template_ssp_id 的專案；舊模式專案＝啟動時複製了一份 SSP 的既有專案。

合規資源庫是顧問替客戶導入法規框架的第一個入口。顧問到客戶現場訪談，手上拿的訪談表就是系統可下載的「現況資料 Excel」；回來把訪談表匯入，同一份表隨訪談次數反覆匯入。之後逐條整理控制項與 AO 的實施狀態、現況說明、備註。

整理到「部分實作」這類條目，顧問要寫出缺了什麼與怎麼補，手上若有可直接給客戶用的範本就附上——這一步就是正式稽核前的事前稽核。以 CRA 的漏洞通報條為例：

缺失若沒有自己的欄位，就只能塞進現況說明：一個欄位同時講「現在是什麼」和「少了什麼」，產缺失報告得人工再拆一次（FR-138 自家 CRA 自評就是這樣）。同一份訪談表重新匯入，還可能把上次填好的欄位清掉（§6.5）。

流程由顧問主導：

1. 顧問在資源庫訪談、匯入、整理，完成客戶的 SSP。
2. 啟動專案。專案直接看資源庫那份 SSP；客戶的專案管理者只指派工作與上傳證據，不編 SSP。
3. 顧問持續訪談、匯入、整理，專案即時看到。
4. 顧問判斷可以請外部稽核了，按「送審」（就是「啟動稽核」）：存一版、凍結一份給稽核輪、資源庫鎖寫。覆核送審走同一套。
5. 稽核流程本身照舊。送審之後到結案，資源庫都鎖住；只有覆核子輪回到規劃中時可以再整理，新年度走「複製資源庫」。

%%{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
    actor C as 顧問
    participant RL as 合規資源庫<br/>（範本 SSP＝工作副本）
    participant V as 版本索引
    participant P as 專案
    participant A as 稽核輪
    C->>RL: 下載訪談表、到客戶現場訪談
    C->>RL: 匯入訪談表（只蓋檔案有填的欄）
    RL->>V: 匯入前自動存一版當備份（source=import-backup）
    loop 整理現況、缺失、建議、附範本
        C->>RL: 暫存（不開版）
        C->>RL: 儲存成新版本
        RL->>V: 存一版（source=manual）
    end
    C->>P: 啟動專案（不複製，直接指向範本 SSP）
    P-->>RL: 規劃頁唯讀讀取同一份
    loop 持續訪談
        C->>RL: 再匯入、再整理、再存版
        RL-->>P: 專案即時看到
    end
    C->>A: 送審（＝啟動稽核）
    A->>V: 存一版（source=submit，記 audit_round_id）
    A->>A: 凍結快照給稽核輪
    Note over RL: 送審後到結案資源庫鎖寫
    C->>A: 覆核送審（同一套：存版、凍結、鎖寫）

整案一句話：顧問在合規資源庫裡把訪談結果寫完整（現況、備註、缺失、修改建議、附範本），每整理一輪就存一版；顧問覺得可以了就送審，送審那刻鎖一版給外部稽核用。專案只看資源庫那一份，不能改。

依賴：子需求一、二可平行；子需求三的送審鎖版用到子需求二的存版。畫面最先出的是資源庫控制項欄位（卡 2）與建議附件（卡 2b）。

6.1 資料模型

① props 新鍵（IR 與 AO statement 都有）：

規則：空字串＝刪掉該鍵（與 _setp 一致）；讀取時沒有該鍵視為空；全部欄位空時 props 回 None（與 _map_to_props 一致）。匯出 docx／Excel、差異比對、合併決策都認得這兩鍵，由共用 helper 一次處理。

② 表 compliance.ssp_control_attachments（建議附件；主線 migration，GRANT cm_app 含 sequence，RLS 依租戶）：

③ 表 compliance.ssp_versions（版本索引；主線 migration，GRANT cm_app 含 sequence，RLS 依租戶）：

唯一鍵 UNIQUE (owner_type, owner_id, version_no)。

④ OSCAL 原生版本欄（不加欄，只開始寫）：每存一版，該版快照與工作副本的 metadata.version 寫版號字串（與 version_label 同步）；metadata.revisions 追加一筆 {version, last-modified, title, remarks, links:[{rel: "predecessor-version", href: "#<前一版 SSP uuid>"}]}。

⑤ public.system_menus 實施狀態 seed（主線 phase=seed，ON CONFLICT DO NOTHING，先例 scripts/sql/2026-05-22-seed-oscal-ssp-roles.sql）：

FE 走 API.SYSTEM_MENU，i18n 走 lang.ssp_implementation_status.<key>；Excel 匯入合法值與 BE 驗證讀同一份；匯出 OSCAL 時 not_applicable 轉 not-applicable。

6.2 三層關係

送審時存的版（source='submit'）與稽核凍結是兩份不同的快照，靠 audit_round_id 互指：前者給顧問回顧比對、帶建議附件；後者給稽核輪當基準、不帶建議附件。稽核凍結快照不進索引表。

6.3 版本操作

存版、還原都是寫入，受資源庫編輯權與稽核中鎖寫管（§6.4）。

6.4 權限分流與鎖寫

範本 SSP 的寫入入口有兩類，規則要在兩類都成立：

送審後鎖寫：範本 SSP 綁定的新模式專案，其當前輪次不是 planning 時（audit_planning、auditing、remediation、pending_reverify、closed），範本 SSP 的所有寫入回 412（D19）；覆核子輪回到 planning 時可改、送審時再鎖。

唯讀的 SSP：版本索引裡的 SSP 與 status='frozen' 的 SSP 一律唯讀；讀取入口要認得版本快照（目前它既不是 living_ssp_id 也不是稽核輪 ssp_id，走共用端點會「找不到」）。

專案側：新模式專案的規劃頁，SSP 資料一律唯讀（D7）；專案管理者帳號直接打寫入 API，因範本 SSP 走資源庫守門而被擋。舊模式專案維持專案守門與既有可寫判斷（D21）。

6.5 匯入兩路徑

新模式專案指向範本 SSP，匯入一律從資源庫做；舊模式專案的專案側 mode="update" 照舊（D21）。docx 匯入不動。

6.6 畫面（甲案）

雛形：prototype/index.html（控制項填寫、版本歷史、版本比對、專案規劃頁唯讀）。

資源庫「適用控制項」頁籤：

• 控制項表單與 AO 表單各在「備註」之後加「缺失」「缺失修改建議」兩個多行文字框。
• 「缺失修改建議」正下方加「建議附件」區塊：上傳只選檔、寫一行說明，可改說明、可刪除。
• 既有「程序書」區塊放在建議附件下方，維持現狀、分開呈現。
• 實施狀態下拉讀 ssp_implementation_status 六值。
• 頁首加「暫存」「儲存成新版本」（填說明）兩顆鈕與「版本歷史」入口；稽核中兩顆鈕停用並提示原因。
• 其他七個頁籤不動。ModuleFrameTemplateEditView.vue 已超標，新欄位、建議附件區塊、頁首鈕一律做成新子元件，原檔只加一行掛載。

版本歷史頁：列版號、來源（手動存版／匯入自動存版／送審鎖版／還原前自動存版）、說明、誰、何時；送審版標對應稽核輪（主稽核或覆核）並顯示鎖頭；每列可檢視（唯讀）、比對、還原。還原確認框列出會改動的筆數，並說明目前工作副本會先存成新版。

版本比對頁：選兩版（或某版對工作副本），只列有差異的控制項與 AO，四態著色。

專案規劃頁（新模式專案）：控制項與 AO 實施層欄位、程序書、建議附件、其他 SSP 頁籤全部唯讀；頁首一行「內容即時同步自合規資源庫」，有資源庫編輯權的人多一個「前往合規資源庫」連結；任務設定照舊可編。ProjectPlanningView.vue 已超標，唯讀旗標與提示做成子元件。

依「決策者何時看得到畫面」排序。e2e 屬母卡收口，不在單卡做。只動一支套件 jedi-oscal-v2（卡 3），開發期走 path dependency，發版等決策者明示。

%%{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
    subgraph S1[子需求一 訪談欄位與匯入]
      C1[卡1 BE 新欄＋共用 helper<br/>＋批次存 API] --> C2[卡2 FE 控制項欄位<br/>＋暫存鈕]
      C1 --> C2b[卡2b 建議附件<br/>表＋API＋畫面區塊]
      C1 --> C3[卡3 Excel 三欄＋狀態選項<br/>＋套件合併規則]
      C1 --> C4[卡4 範本 460 回填]
    end
    subgraph S2[子需求二 資源庫版本]
      C5[卡5 版本索引表＋存版 API] --> C6[卡6 版本歷史頁<br/>＋存版暫存鈕]
      C5 --> C7[卡7 比對與還原]
    end
    subgraph S3[子需求三 一對一與唯讀]
      C8[卡8 啟動改指向<br/>＋一對一守門] --> C9[卡9 規劃頁唯讀<br/>＋顧問編輯權]
      C8 --> C10[卡10 送審鎖版<br/>＋稽核中鎖寫]
    end
    C1 --> C5
    C2b --> C5
    C5 --> C10

上版檢查項：STG／POC 上線前查有無「一資源庫多專案」（D21）；兩張新表與 seed 的 migration 照環境異動鐵則只先套 DEV，寫完回報出貨基線待重產。

用 DEV 一個 CRA 資源庫（建議 460），批次走完再一次回報：

1. 資源庫「適用控制項」頁籤：某條控制項與其一個 AO 填實施狀態「部分實作」、現況、備註、缺失、缺失修改建議；在建議附件各掛一份檔案並寫說明 → 按「暫存」→ 重新整理，全部還在；程序書區與「程序書文件池」頁籤看不到建議附件；實施狀態下拉有六項、含「未評估」。
2. 下載訪談表，「適用控制項」分頁看到備註、缺失、缺失修改建議三欄且帶出剛填的值；在另一條只填「缺失」、其他欄留白，重新匯入 → 該條現況說明沒被清掉、其他條不變；版本歷史多一列「匯入自動存版」。
3. 再改兩條控制項 → 「儲存成新版本」填說明 → 版本歷史多一列「手動存版」；檢視上一版，所有欄位不能改。
4. 比對這兩版 → 只列出那兩條，差異著色。
5. 還原到較早那版 → 確認框列出會改動的筆數並說明目前工作副本會先存成新版 → 確定 → 歷史多一列「還原前自動存版」，內容回到那版；再還原回去，內容一字不差，程序書與建議附件都在。
6. 用此資源庫啟動專案 → 在資源庫改一條現況，專案規劃頁立刻看到；規劃頁控制項與 AO 欄位全灰、頁首提示同步自資源庫；任務指派與到期日仍可改。同一資源庫再啟動一次被擋（含該專案已結案或封存後）；有專案綁著時刪資源庫被擋。
7. 用專案管理者帳號直接打 SSP 共用寫入端點（例如系統特性）改這份 SSP → 被擋。
8. 專案送審（啟動稽核）→ 資源庫暫存與存版鈕停用；版本歷史多一列「送審鎖版」標主稽核輪；直接打寫入 API 回 412。
9. 輪次推進到整改、結案 → 資源庫仍唯讀。開覆核子輪回到規劃中時可再編輯；覆核送審後再鎖，版本歷史多一列標覆核輪。
10. 複製此資源庫 → 新資源庫控制項內容、程序書、建議附件、表單設定齊全，版本歷史是空的。
11. 一個舊模式專案（啟動時複製了 SSP 的既有專案）：規劃頁與寫入行為和上線前相同。