資源庫樣板編輯器（ModuleFrame Template Editor）

功能群：合規框架與 SSP｜上層導航頁見 範本管理 / 合規資源庫｜資產模型先讀 功能群總覽；OSCAL SSP 領域概念見 oscal-knowledge

事實基準：2026-07-05 從 FE ModuleFrameTemplateEditView.vue + BE code 掃出；endpoint 對 routes.json、schema 對 db_schema.json、error code 開檔驗（module_frame_error_code.py）

變更紀錄

1. 功能描述

資源庫樣板編輯器是 範本管理 清單「樣板編輯」導向的內容編制面板（ModuleFrameTemplateEditView.vue）：把資源庫綁定的樣板 SSP（module_frames.template_ssp_id 指向的 oscal.system_security_plans）內容全部編在此。這是單一真相來源——讀取與寫入都走同一份樣板 SSP，專案成立 clone 時原樣帶入。

編輯器以多個 tab 組織，本質是範本版的 SSP 編輯器：受評標的（system-characteristics）、負責單位 / 人員（parties）、元件 / 外部授權 / 資產（components / leveraged / inventory）這幾個子區，與 專案 SSP 編輯器 是同一套資料結構、同一批可重用元件（ModuleFramePartiesPanel.vue 等 SSP 與範本共用），差別只在 API base（範本走 /module-frame/{uid}/…，SSP 走 /ssp/{ssp_uid}/…）與編輯 gate（範本以資源庫作者能力守門、SSP 以 manager + AP=planning 守門）。因此這些子區的 field-level 逐欄規格交叉引用 SSP 子頁、不在此重複。

樣板編輯器特有、無 SSP 子頁對應的兩塊是 適用控制項現況預設值（control-defaults / objective-defaults，UC-MF-01 core，體現「lazy upsert 對樣板 SSP IR 寫入」）與 程序書池（reference-documents，掛控制 / AO 雙 context），於本頁自述。

主要使用者：資源庫作者（管理員）；scope=SYSTEM 公版由 root 租戶 admin 維護。

角色速覽（本群非專案層角色，見 _overview §5）：資源庫作者（管理員）為主；scope=SYSTEM 公版 root 租戶維護。

1.1 功能總覽（本頁全部功能）

本頁是樣板 SSP 多 tab 編輯器：與 專案 SSP 編輯器 共用資料結構的子區（單位/人員/元件/授權/資產/受評標的），逐欄規格交叉引用對應 SSP 子頁（只寫 API base 差異）；範本特有子區（適用控制項預設值、程序書池）於本頁自述。

UC（§2）只展開本頁具實質後端邏輯、且無 SSP 子頁可交叉引用的核心：適用控制項現況預設值編輯（1，UC-MF-01——最能體現「樣板 SSP 單一真相來源 + lazy upsert」）。共用 SSP 子區的 CRUD 流程與逐坑見對應 SSP 子頁；匯入 / 匯出精靈（10）另屬 匯入精靈頁，此處只交叉連結不重複。

2. Use Case

角色速覽（同 §1）。

流程圖視覺慣例：菱形 = 判斷、橘底 = 例外 / 擋下、紅框 = 錯誤（標 error code）、綠框 = 成功終點、虛線 = 可選路徑。

UC-MF-01 編輯控制項 / AO 現況預設值

共用 SSP 子區（單位 / 人員 / 元件 / 授權 / 資產 / 受評標的）的 CRUD UC 與 M2M 坑，見 SSP 編輯器 UC-SE-01 及各子頁 UC；本頁不重述。

3. 權限矩陣

本頁多為 JWT + 選單能力守門；細粒度前置以 error code 表達（見 §4）。scope=SYSTEM 公版的寫入權另受 root 租戶約束。與 SSP 編輯器守門的差異：SSP 走 require_participant（讀）/ require_manager + AP=planning（寫）；範本走資源庫作者能力，無專案角色 / AP 概念。

4. 狀態機與前置條件

5. UI 設計

實機截圖（STG，亮色模式，2026-07-05，帳號 blsadmin）：

版面骨架（三頁全景，本頁＝頁3）：

狀態呈現：樣板編輯 draft/published 徽章；適用控制項 tab 為控制樹 + AO 現況表單；無 socket，寫入後本地更新 + 重載。

6. API 規格

Envelope：成功 {"status": true, "data": …, "meta": …}、失敗 {"error_code": "…", "msg": "…"}。

6.1 總清單（本頁呼叫的全部 endpoint）

交叉引用約定：受評標的 / 單位 / 人員 / 元件 / 授權 / 資產六個子區的 request / response 逐欄表、jsonb 內部結構、props 保留鍵、逐坑，與對應 SSP 子頁 完全相同（同一批可重用元件 + 同一資料結構），差別只有 API base 前綴（本頁 /module-frame/{uid}/…，SSP /ssp/{ssp_uid}/…）與編輯 gate（見 §3）。故此處只列 base，逐欄請點對應子頁 §6，避免兩份文件各記一套而失同步。

6.2 核心 endpoint（範本特有）

以下兩塊為樣板編輯器特有、無 SSP 子頁對應，於本頁完整描述。

[PUT] /module-frame/{uid}/control-defaults/{control_identifier}

控制項現況預設值 lazy upsert（IR 不存在自動建、控制項留在 profile）。

Request：

解析 module_frame_uid → template_ssp_id → 對樣板 SSP 的 ssp_implemented_requirements upsert。DELETE = 清值保留 IR。前置：控制屬 profile（否則 MODULE_FRAME_400001）、有樣板 SSP（否則 MODULE_FRAME_404004）。出處：app/module_frame/service/module_frame_control_default_service.py

[GET/PUT/DELETE] /module-frame/{uid}/objective-defaults[/{uid}]

AO（評估目標）現況預設值：對樣板 SSP 的 ssp_statements props upsert（AO key 統一 _obj.N）。前置：AO 屬該控制項（否則 MODULE_FRAME_400002）。出處：app/module_frame/service/module_frame_objective_default_service.py（objective-defaults path）。

[GET/POST/PUT/DELETE] /module-frame/{uid}/reference-documents[/{doc_uid}]

程序書池：掛控制項或 AO 的雙 context 關聯。同一 oscal.ssp_reference_documents 表以 context_type / context_id 分別掛控制項或 AO（雙 context）。上傳走檔案儲存後建關聯；刪除清關聯。出處：app/module_frame/service/module_frame_reference_document_service.py。

7. 前端檔案地圖（compliance-manager-fe/）

共用元件的內部行為（欄位、Dialog、M2M 坑）見對應 SSP 子頁 §7。

8. 後端檔案地圖（本頁核心鏈路）

DDD 提醒：所有內容編輯解析到 template_ssp_id 對樣板 SSP 寫入（單一真相來源）；勿在本群另建 sidecar 表存預設值。子資源鏈路與 SSP 編輯器 §8 是同結構、不同 base。

9. DB

9.1 資料表總清單（本頁讀寫的表）

9.2 ER 圖

9.3 核心表欄位（取自 DEV DB dump，含 DB comment）

範本特有的兩塊寫入表（現況預設 / 程序書）欄位語意如下；共用 SSP 子表的完整欄位卡（含 jsonb 內部結構、props 保留鍵）見對應 SSP 子頁 §9.3（本頁與其同結構、不重複）。

• oscal.ssp_implemented_requirements（control-defaults）：控制項現況預設，props 存 implementation_status/description/responsible_role/control_origination；lazy upsert，DELETE 清值保留 IR。
• oscal.ssp_statements（objective-defaults）：AO 現況預設，AO key _obj.N。
• oscal.ssp_reference_documents（程序書池）：以 context_type/context_id 掛控制項或 AO（雙 context）。

10. 頁面邏輯與資料對應

載入：進頁各 tab GET 對應子資源（control-defaults / objective-defaults / reference-documents / parties / components / leveraged / inventory / system-characteristic）。

關鍵欄位對應：

儲存流程：各子資源獨立 PUT / POST（lazy upsert 對樣板 SSP）；讀寫同源。

錯誤對應：MODULE_FRAME_400001（控制不屬 profile）/ 400002（AO 不屬控制）/ 404004（無樣板 SSP）/ 400003-400004（匯入檔）/ 409001-409005（子資源名稱重複）。

11. 背景行為與外部依賴

12. 邊界情況與已知坑

1. 樣板 SSP 單一真相來源：控制預設 / AO / 元件 / 人員 / 系統特性 / 程序書全部讀寫 template_ssp_id 指向的樣板 SSP，不要另建 sidecar 表存預設值（會變第二套真相）
2. lazy IR upsert：control-defaults 首次 PUT 建 IR、後續更新；DELETE 清值保留 IR（控制留在 profile）
3. 可翻譯欄位要傳 locale：module_frames_trans 存翻譯，不傳 locale 的 update 對前端 failover 讀取無效
4. 程序書雙 context：同一 ssp_reference_documents 表以 context_id/type 分別掛控制項或 AO
5. 共用 SSP 子區的坑同 SSP 子頁：資產 M2M implemented_components 編輯鎖定、party 軟式參照、資產設備 merge vs 系統 full-replace 等坑，與 SSP 資產 §12 / SSP 編輯器 §12 相同（同一批元件 / 同結構）；本頁只在 API base 與 gate 上不同。
6. 範本無 AP=planning gate：SSP 編輯器以 AP=planning + manager 守門，範本編輯器以資源庫作者能力守門、無專案 / AP 概念——移植 SSP 子頁描述時勿把 AP gate 誤套到本頁。

13. 開發與驗證

• 跑起來：BE python main_socketio.py（port 8000，log 在 log/app.log）；FE Vite dev server。BE 改 service code 必重啟
• 測試帳號：資源庫作者 / 管理員；scope=SYSTEM 需 root 租戶帳號（密碼見 .env / 部署文件）
• 導航路徑：側邊選單「範本管理 / 合規資源庫」→ 某列「樣板編輯」（/module-frame/module-frame/:uid/template-edit）
• 前置資料：需一個框架版本 + profile；樣板 SSP 由建立資源庫時生成；建幾筆元件 / 授權 / 資產測共用子區 CRUD
• E2E：compliance-manager-test/ repo；以 樣板編輯 / module-frame / ModuleFrameTemplateEdit 搜尋
• 相關文件：上層導航 範本管理；共用資料結構 SSP 編輯器（基本資料 / 參與方 / 元件 / 授權 / 資產）；匯入精靈 module-frame-import；memory feedback_mf_defaults_single_source_of_truth