手冊首頁／合規稽核／合規框架與 SSP 功能群總覽

合規框架與 SSP 功能群總覽

本檔放「本功能群多個頁面共用的知識」：頁面地圖、合規資產模型、發布生命週期、匯入解析三步式、角色基調。

各頁面 spec 引用本檔，只寫自己頁面的差異——改共用邏輯時改這裡一份。

1. 頁面地圖

本群是合規資產的作者端（authoring layer）：在專案消費這些資產之前，於此建立可重用的框架、資源庫、稽核流程範本。

頁面	FE route	用途一句話	spec
合規框架管理	`/compliance-framework/compliance-framework-manage`	框架（CMMC / ISO27001…）CRUD、進入版本管理	⬜ compliance-framework-manage.md
框架版本管理	`.../compliance-framework-version-manage`	某框架下的版本清單、發布、看 catalog	併入 manage spec
框架版本匯入 / 編輯	`.../import-version/:parseUid?`・`.../framework-version/:uid/edit`	從 PDF/OSCAL 匯入版本控制集、編輯	⬜ compliance-framework-import-version.md
範本管理（ModuleFrame / 資源庫）	`/module-frame/module-frame`・`-items`・`:uid/template-edit`	合規資源庫（可 clone 三件組）CRUD、內容維護	⬜ module-frame.md
範本匯入精靈（docx / excel）	`/module-frame/import-docx`・`import-excel`（+ update / preview）	從 docx / excel 匯入資源庫內容	⬜ module-frame-import.md
SSP docx 匯入 / 更新	`/project/projects/:id/ssp-import-docx`	專案 SSP 從 docx 匯入 / 更新	⬜ project-ssp-import-docx.md
BPMN 稽核範本管理	`/flow/template-manage`・`template-create`・`template-edit`	稽核流程 BPMN 範本 CRUD / 設計器	⬜ flow-template-manage.md

2. 核心資產模型（本群最重要）

合規資產模型：框架→版本→catalog；資源庫 = published 三件組 + flow template；下游專案 clone 消費

三條資產線：

合規框架線：oscal.frameworks（框架，如 CMMC）→ oscal.framework_versions（版本，publish_status 生命週期、parent_id 版本血緣）→ oscal.catalogs（該版本控制項全集的 OSCAL 落地，與版本 1:1，由匯入解析生成）→ catalog_groups / catalog_controls / catalog_control_parts（三層 + AO part）。
合規資源庫線（ModuleFrame）：compliance.module_frames = 可被專案 clone 的三件組（catalog + profile + SSP）+ audit_flow_template_uid（預設稽核流程）。專案成立時 clone 這組脫鉤公版成 living SSP（見專案管理群 project-create）。
稽核流程線：compliance.flow_templates = BPMN 2.0 稽核流程範本（is_builtin / status draft→published / bpmn_xml）；被 module_frame 與稽核輪次引用驅動狀態機。

下游消費：專案成立 clone 資源庫三件組、綁 flow_template；本群改的是「公版 / 範本」，專案 clone 後即脫鉤，改範本不影響已成立專案。

3. 發布生命週期（draft → published）

框架版本：framework_versions.publish_status——資源庫只能選 published 版本（FR-038 §42）。未發布版本可繼續編輯 catalog。
流程範本：flow_templates.status = draft | published（另有 is_active 軟刪除、is_builtin 系統內建）；PUT .../publish・.../unpublish 切換。
資源庫（module_frame）：enable 旗標決定可否用於成立專案（未發布 → GRC_412031）。

4. 匯入解析三步式（parse → 預覽 → confirm，全群共用）

框架版本 / 資源庫 / SSP 的檔案匯入都走暫存 parse job 三步式（避免半成品直接污染正式表）：

匯入三步：parse 生暫存 job → 線上預覽/驗證/修正 → confirm 寫正式表；取消則 DELETE parse job

資產	parse	取回 / 確認	暫存表
框架版本（PDF/OSCAL）	POST `/oscal-framework-parse-jobs/parse`	GET `/oscal-framework-parse-jobs/{uid}` → POST `.../{uid}/confirm`	`oscal.framework_parse_jobs`
資源庫 docx	POST `/module-frame/import-docx` 系	預覽 → confirm	—
資源庫 / SSP excel	POST `/ssp-excel-imports/parse` → `.../{uid}/confirm`	GET `/ssp-excel-import/{uid}`	`oscal.ssp_excel_parse_jobs`
SSP docx	POST `/ssp-docx-imports/parse` → `.../{uid}/confirm`	GET `/ssp-docx-import/{uid}`	`oscal.ssp_docx_parse_jobs`

5. 角色基調

角色是誰：本群不是 manager/auditor/viewer 這種專案角色，而是框架 / 範本管理者（通常是租戶或平台層被授權者）——維護公司通用的合規框架版本、資源庫範本、BPMN 稽核流程，供之後所有專案 clone 使用。「身為框架管理者，我要先把 CMMC / ISO27001 等框架版本與範本庫建好，讓專案成立時可以直接套用，不用每個專案重新輸入控制項。」一般使用者多半只在專案成立時「消費」這些範本，不會進到本群頁面編輯。

本群是系統 / 租戶層資產作者端，非專案層角色（manager/auditor/viewer 不適用）。權限以能力（capability）/ 選單權限控管（ui_routes + RBAC 三層，見 docs/claude/ 權限系統 SOP）——各頁的實際 endpoint 守門以該頁 §3 為準（多數為 JWT + 選單能力；catalog / framework 寫入屬管理者操作）。

6. 本群共用的已知坑

框架版本 catalog 1:1：一個 framework_version 對一份 catalog（catalog_id 匯入後回填）；別把「版本」與「catalog」當兩個獨立東西改
資源庫 clone 後脫鉤：改 module_frame 不影響已成立專案（專案 clone 的是當下快照）；要影響既有專案得走專案內編輯
可翻譯欄位：module_frames / flow_templates / workflow_templates 有 _trans 表；寫入含翻譯欄位要傳 locale（見 docs/claude/translatable-fields.md）
flow_template vs workflow_template 兩層：flow_templates（作者端 BPMN 範本）≠ workflow_templates（專案 / AO clone 出的執行期範本）；勿混
parse job 是暫存：未 confirm 的解析結果在 *_parse_jobs 暫存表，可 DELETE 放棄；confirm 才入正式表