範本管理 / 合規資源庫（ModuleFrame）
事實基準：2026-07-05 從 FE / BE code 掃出；endpoint 對
routes.json、schema 對db_schema.json、error code 開檔驗（module_frame_error_code.py）
變更紀錄
| 日期 | FR | 變更 |
|---|---|---|
| 2026-07-06 | FR-047 | 改造成 hub 導航頁：明細下鑽拆至 資源庫明細、樣板編輯器拆至 樣板編輯器；本頁保留頁1 清單 CRUD / 複製 / enable 與子頁導航 |
1. 功能描述
範本管理是合規資源庫（ModuleFrame）的作者端。資源庫
= 專案成立時可 clone 的三件組（catalog + profile + 樣板
SSP）+
預設稽核流程範本；綁定一個框架版本（oscal_framework_version_uid）與基準線（oscal_profile_uid），內容全部編在
template_ssp_id 指向的樣板
SSP（oscal.system_security_plans；識別靠
template_ssp_id，非 is_template 欄，見
§9）——這是單一真相來源：讀取與寫入都走同一份樣板
SSP。
本頁作為導航 hub：頁1 清單（資源庫 CRUD / 複製 / enable 切換 / 下載）留在本頁，明細下鑽與樣板編輯器各自拆成獨立子頁。
三個相連頁面的分工：
- 頁 1
清單（本頁）（
ModuleFrame.vue）：資源庫 CRUD、複製、enable 切換、下載 SSP 樣板。 - 頁 2
明細（
ModuleFrameDetail.vue）：群組→控制項→AO 下鑽檢視，見 資源庫明細。 - 頁 3
樣板編輯（
ModuleFrameTemplateEditView.vue）：多 tab 編樣板 SSP 全部內容，見 樣板編輯器。
主要使用者：資源庫作者（管理員）；scope=SYSTEM
的系統公版由 root 租戶 admin 維護、人人可讀。
角色速覽（本群非專案層角色，見 _overview
§5）：資源庫作者（管理員）為主；scope=SYSTEM 公版 root
租戶維護。
1.1 功能總覽（本頁全部功能）
本頁是 hub（清單 CRUD + 列操作 + 子頁導航）：明細下鑽與樣板編輯器（含各子資源 field-level 逐欄規格）拆成子頁，見「詳述」欄連結。
| # | 功能 | 說明 | 位置 | 詳述 |
|---|---|---|---|---|
| 1 | 資源庫清單 / 篩選 | 分頁；篩選 status/enable/provider/framework/group | 頁1 表格 | §6.2 |
| 2 | 建立資源庫 | 手動 / docx / excel（→ import 精靈） | 頁1 建立下拉 | →import |
| 3 | 複製資源庫 | clone 整組三件組（deep-copy 脫鉤） | 頁1 操作 | UC-MF-02 |
| 4 | 編輯基本資訊 | name / group / description / provider / frequency | 頁1 dialog | §6.2 |
| 5 | enable 切換 / 刪除 | 是否可用於成立專案；軟刪除（is_delete） |
頁1 操作 | §12 |
| 6 | 明細下鑽 | 群組→控制項→AO；頻率 / 風險 / 責任部門 / 任務 | 頁2 | 資源庫明細 |
| 7 | 樣板內容編輯 | 適用控制項 / 受評標的 / 負責單位 / 元件·授權·資產 / 程序書池；多 tab 編樣板 SSP | 頁3 | 樣板編輯器 |
| 8 | 匯入 / 匯出 | control-defaults Excel 匯入匯出；SSP OSCAL 匯出；整包 import | 頁1/3 | 樣板編輯器 §6 / import 精靈 |
UC（§2）展開本頁具實質後端邏輯的清單層功能：複製資源庫（3，UC-MF-02——三件組 deep-copy 脫鉤）。清單顯示（1）、建立（2）屬常規讀寫；明細下鑽（6）見 資源庫明細、樣板內容編輯（7，UC-MF-01 core）見 樣板編輯器；匯入 / 匯出精靈（8）於 匯入精靈頁，此處只交叉連結不重複。
2. Use Case
角色速覽（本群非專案層角色，見 _overview
§5）：資源庫作者（管理員）為主；scope=SYSTEM 公版 root
租戶維護。
流程圖視覺慣例：菱形 = 判斷、橘底 = 例外 / 擋下、紅框 = 錯誤（標 error code）、綠框 = 成功終點、虛線 = 可選路徑。
本頁只保留清單層 UC；樣板內容編輯的核心 UC-MF-01（控制項 / AO 現況預設值）拆到 樣板編輯器。
UC-MF-02 複製資源庫（三件組 deep-copy 脫鉤）
| 項目 | 內容 |
|---|---|
| 角色 | 資源庫作者 |
| 前置條件 | 已選中一筆來源資源庫（source_mf_uid） |
| 產出 / 後置條件 | deep-copy 建新 module_frames + 新樣板 SSP（新
template_ssp_id + profile）成脫鉤公版；來源
template_ssp_id 不動；日後改複本不影響來源 / 已成立專案（見
§12 坑 3） |
3. 權限矩陣
| 操作 | FE 判定 | BE 強制 | BE 檢查位置 |
|---|---|---|---|
| 讀 / 清單 | 登入 + 選單權限 | @jwt_required() |
route |
| 資源庫 CRUD / 複製 | 選單能力（作者） | @jwt_required() + 業務前置（名稱不重複…） |
app/module_frame/service/* |
| 成立專案用（下游） | enable + published | 未發布 → GRC_412031（在 project-create，非本頁） |
project_start_app_service |
本頁多為 JWT + 選單能力守門；細粒度前置以 error code 表達（見 §4 / §10）。
scope=SYSTEM公版的寫入權另受 root 租戶約束。樣板內容編輯的前置（控制屬 profile、子資源名稱不重複…）見 樣板編輯器 §3。
4. 狀態機與前置條件
本頁（清單層）gate：
| 條件 | 效果 | 出處 |
|---|---|---|
| enable=1 且 published | 才可用於成立專案 | 下游 project-create |
| is_delete=1 | 軟刪除，不列於清單 | module_frames.is_delete |
樣板內容編輯的前置（控制項不屬 profile →
MODULE_FRAME_400001、無樣板 SSP →
404004、子資源名稱重複 →
409001~409005、匯入檔格式 → 400003/400004）見
樣板編輯器
§4。
5. UI 設計
實機截圖（STG，亮色模式，2026-07-05，帳號 blsadmin）：
版面骨架（三頁全景）：
狀態呈現：清單狀態 / enable 徽章。明細下鑽與樣板編輯器狀態呈現見各子頁 §5。
6. API 規格
Envelope：成功
{"status": true, "data": …, "meta": …}、失敗
{"error_code": "…", "msg": "…"}。
6.1 總清單（本 hub 呼叫的 endpoint）
| 分類 | Method + Path | 說明 | 完整規格 |
|---|---|---|---|
| 清單 / CRUD | GET/POST /module-frame、GET/PUT/DELETE
/module-frame/{uid} |
資源庫讀 / 建 / 改 / 刪 | §6.2 |
| 選單 | GET /module-frame（filter published） |
下拉（成立專案 / 篩選） | GAI-SD-02 |
| 複製 | POST /module-frame/clone |
clone 三件組 | §6.2 |
| 下載 | GET
/module-frame/download/{template,yaml-template} |
空白匯入樣板 | GAI-SD-02 |
樣板內容編輯的全部 endpoint（control-defaults / objective-defaults / parties / components / leveraged / inventory / system-characteristic / reference-documents / ssp 匯出入）見 樣板編輯器 §6。
6.2 核心 endpoint
[GET|POST] /module-frame（清單 / 建立）
清單 Request：
| 欄位 | 型別 | 必填 | 說明 |
|---|---|---|---|
| pager | object | 否 | 分頁參數 |
| sort | object | 否 | 排序參數 |
| filters | object | 否 | 篩選條件（見下列子欄位） |
| filters.enable | — | 否 | 是否啟用 |
| filters.status | — | 否 | 狀態 |
| filters.provider | — | 否 | 提供者 |
| filters.group | — | 否 | 群組 |
| filters.framework_version_uid | — | 否 | 框架版本 |
| filters.profile_uid | — | 否 | 基準線 |
建立 Request body：
| 欄位 | 型別 | 必填 | 說明 |
|---|---|---|---|
| name | string | — | 名稱 |
| group | string | — | 群組 |
| description | string | — | 描述 |
| provider | string | — | 提供者 |
| frequency | — | — | 頻率 |
| oscal_framework_version_uid | varchar(36) | — | 綁定的框架版本 |
| oscal_profile_uid | varchar(36) | — | 綁定的基準線 |
Response data[]： ModuleFrameDTO（+
meta）
| 欄位 | 型別 | 說明 |
|---|---|---|
| uid | varchar(36) | 唯一識別碼 |
| name | string | 名稱 |
| group | string | 群組 |
| provider | string | 提供者 |
| version | — | 版本 |
| frequency | — | 頻率 |
| enable | int | 是否啟用 |
| framework | — | 綁定的框架版本 |
| profile | — | 綁定的基準線 |
| audit_flow_template_uid | varchar(36) | 預設稽核流程範本 |
| … | — | … |
出處：api/module_frame/routes/module_frame_route.py::ModuleFramesRoute、app/module_frame/service/module_frame_service.py::get_module_frames_and_pager
[POST] /module-frame/clone
clone 整組三件組（新 module_frame + 新樣板 SSP +
profile）成脫鉤公版。Request：source_mf_uid（+
選填參數）。出處：app/module_frame/service/*clone*
7. 前端檔案地圖（compliance-manager-fe/）
| 檔案 | 角色 |
|---|---|
src/views/module_frame/ModuleFrame.vue |
頁1 清單 CRUD / 複製 / enable（本頁） |
src/views/module_frame/ModuleFrameDetail.vue |
頁2 群組→控制項→AO 下鑽（見 資源庫明細） |
src/views/module_frame/ModuleFrameTemplateEditView.vue |
頁3 樣板編輯 tab（見 樣板編輯器） |
src/config/router/index.js:431-448 |
routes module-frame / -items /
-template-edit |
src/config/api/api.js |
endpoint 常數（MODULE_FRAME 等） |
src/config/locales/i18n/zh-tw/module-frame.json |
頁面 i18n |
8. 後端檔案地圖（本頁核心鏈路）
| 鏈路 | Route | App Service | 底層 |
|---|---|---|---|
| 清單 | api/module_frame/routes/module_frame_route.py::ModuleFramesRoute |
app/module_frame/service/module_frame_service.py::get_module_frames_and_pager |
domain/module_frame/service/module_frame_domain_service（join
framework_version + profile） |
| 複製 | module_frame_route.py（clone 端點） |
module_frame_service.py（clone） |
deep-copy 三件組 |
樣板內容編輯的鏈路（control-defaults / 子資源）見 樣板編輯器 §8。
DDD 提醒：所有內容編輯解析到
template_ssp_id 對樣板 SSP
寫入（單一真相來源）；勿在本群另建 sidecar 表存預設值。
9. DB
9.1 資料表總清單（本頁讀寫的表）
| 表 | 讀/寫 | 說明 | 欄位詳述 |
|---|---|---|---|
| compliance.module_frames | 讀 / 寫 | 資源庫主檔（三件組指標 + enable + scope） | §9.3 |
| compliance.module_frames_trans | 讀 / 寫 | name / description / group 翻譯 | GAI-SD-03 |
| oscal.system_security_plans | 讀 | 樣板 SSP（module_frames.template_ssp_id 指向）— clone
時複製 |
樣板編輯器 §9 |
| oscal.profiles / catalogs | 讀 | 綁定的基準線 / 控制母體 | GAI-SD-03 |
樣板 SSP 底下子表（ssp_implemented_requirements / ssp_statements / ssp_components / parties…）的讀寫在 樣板編輯器 §9。
9.2 ER 圖
9.3 核心表欄位（取自 DEV DB dump，含 DB comment）
compliance.module_frames — 合規資源庫主檔
| 欄位 | 型別 | 說明 |
|---|---|---|
| uid | varchar(36) | 唯一識別碼 |
| name / group / provider / version / frequency | varchar | 基本資料 |
| enable | int | 是否啟用（可否用於成立專案） |
| oscal_framework_version_uid | varchar(36) | 綁定的框架版本 |
| oscal_profile_uid | varchar(36) | 綁定的基準線 |
| template_ssp_id | int | 樣板 SSP（oscal.system_security_plans.id）—
內容編輯的單一真相來源（FR-036）。⚠️ 樣板 SSP
的識別/連結靠本欄 template_ssp_id
指向；add_empty_ssp(is_template=True) 是 FR-036
建立時語意，但 is_template 在現行 v2
system_security_plans 非 live DB
欄位（FR-036 migration 針對舊表名 oscal.ssps，v2
實際表為 system_security_plans），故不可用
WHERE is_template=true 查樣板 SSP |
| audit_flow_template_uid | varchar(36) | 預設稽核流程範本 → compliance.flow_templates.uid（soft
ref） |
| scope | varchar(20) | tenant scope：SYSTEM=系統公版（admin 維護 / 人人可讀 / owner=ROOT tenant） |
| is_delete | int | 軟刪除（0=正常 / 1=已刪除） |
10. 頁面邏輯與資料對應
載入：頁1 GET /module-frame（分頁
body）。
關鍵欄位對應：
| 畫面元素 | API 欄位 |
|---|---|
| 清單狀態 / enable 徽章 | ModuleFrameDTO enable / status |
| 框架 / 基準線欄 | framework / profile（join 帶出） |
儲存流程：清單層 CRUD 各自 POST/PUT/DELETE；樣板內容編輯的載入 / 儲存見 樣板編輯器 §10。
錯誤對應：清單層以常規 CRUD 前置為主；樣板內容編輯的
error code（MODULE_FRAME_400001 等）見 樣板編輯器
§10。
11. 背景行為與外部依賴
| 類型 | 內容 |
|---|---|
| 匯入解析 | control-defaults Excel / 整包 import 走解析（見 _overview §4 與 module-frame-import） |
| 可翻譯欄位 | module_frames 有 _trans；寫
name/description/group 要傳
locale（docs/claude/translatable-fields.md） |
| Socket | 本頁無 socket |
| jedi-* 套件 | jedi-oscal-v2（樣板 SSP / catalog / profile） |
| 系統參數 | scope=SYSTEM 公版；enable 決定成立專案可用性 |
12. 邊界情況與已知坑
- 樣板 SSP 單一真相來源：控制預設 / AO / 元件 / 人員
/ 系統特性 / 程序書全部讀寫
template_ssp_id指向的樣板 SSP，不要另建 sidecar 表存預設值（會變第二套真相）。細節坑見 樣板編輯器 §12 - clone deep-copy 脫鉤：複製建新 module_frame + 新樣板 SSP；舊 template_ssp_id 不動；專案成立時也是 clone 這組，改資源庫不影響已成立專案
- 可翻譯欄位要傳
locale：
module_frames_trans存翻譯，不傳 locale 的 update 對前端 failover 讀取無效 - enable / published 才可成立專案：未啟用 / 未發布 →
下游
GRC_412031（在 project-create） - scope=SYSTEM 公版：系統公版由 root 租戶 admin 維護、人人可讀；一般租戶改不動
- 軟刪除是
is_delete不是 deleted_at：本表用is_delete（0/1），與 projects 的deleted_at慣例不同
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）→ 明細 / 樣板編輯 - 前置資料：需一個框架版本 + profile；樣板 SSP 由建立資源庫時生成
- E2E：
compliance-manager-test/repo；以資源庫/module-frame/ModuleFrame搜尋 - 相關文件：資源庫明細、樣板編輯器、匯入精靈 module-frame-import、下游消費 project-create、資產模型
_overview；memory
feedback_mf_defaults_single_source_of_truth