手冊首頁 ／ 合規稽核 ／ 合規框架管理

合規框架管理（Compliance Framework Manage）

功能群：合規框架與 SSP｜資產模型與發布生命週期先讀 功能群總覽

事實基準：2026-07-05 從 FE / BE code 掃出；endpoint 對 routes.json、schema 對 db_schema.json、error code 開檔驗

1. 功能描述

合規框架管理是框架與框架版本的作者端（兩個相連頁面合一 spec）：管理合規框架（CMMC 2.0 / ISO27001…）及其版本，每個版本對應一份 catalog（控制項全集）。框架是全域資源，僅平台（root 租戶）管理員可編輯；一般使用者唯讀。

  • 頁 1 框架清單（ComplianceFrameworkManage.vue）：框架 CRUD，點名稱進版本管理。
  • 頁 2 版本管理（ComplianceFrameworkVersionManage.vue）：某框架下的版本清單、建立 / 編輯 / 刪除、匯入版本（→ import-version）、看 catalog 詳情、下載 OSCAL。

主要使用者：平台管理員（寫）／所有登入者（讀）。

角色速覽（本群非專案層角色，見 _overview §5）：

角色 一句話
platform admin 平台（root 租戶）管理員 — 唯一可寫（CRUD / 匯入 / 刪除）
一般登入者 只能檢視框架 / 版本 / catalog

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

# 功能 說明 位置 詳述
1 框架搜尋 / 重設 name / code / authority 關鍵字 頁1 篩選列 §10
2 框架 CRUD 建立 / 編輯（name/main_version/authority/publish_status/description）/ 刪除（draft-only） 頁1 按鈕 + dialog UC-CFM-01
3 框架批次刪除 多選（自動濾 draft），platform admin 頁1 Header UC-CFM-02
4 進版本管理 點框架名稱 → 頁2 頁1 名稱連結 §10
5 版本清單 / 搜尋 某框架的版本（version / publish_status） 頁2 表格 §6.2
6 版本 CRUD 建立 / 編輯（version/release_date/publish_status）/ 刪除（draft-only） 頁2 按鈕 + dialog UC-CFM-01
7 匯入版本 從 PDF/OSCAL 匯入版本控制集 頁2 → import-version 頁 →import-version
8 版本詳情（catalog） 雙欄：左 PDF、右控制項樹（群組→控制項→AO/指引） 頁2 dialog §6.2
9 子版本 版本可巢狀（parent_id）；無 catalog 的版本 → 子版本清單 頁2 名稱連結 §12
10 OSCAL 下載 匯出版本 catalog 為 OSCAL JSON 頁2 操作 UC-CFM-03
11 發布狀態 draft / published；published 鎖刪除 頁1/2 欄 _overview §3

UC（§2）展開本頁所有具實質後端邏輯的功能：框架 / 版本 CRUD 與 catalog 導覽（2/6/8/9/11，UC-CFM-01）、框架批次刪除（3，UC-CFM-02）、OSCAL 下載（10，UC-CFM-03）。純顯示 / 導覽類（1 搜尋、4 進版本管理、5 版本清單）見 §10；版本匯入（7）跨頁另有 import-version 專屬 spec，於此只交叉連結不重複。

2. Use Case

角色速覽（本群非專案層角色，見 _overview §5）：

角色 一句話
platform admin 平台（root 租戶）管理員 — 唯一可寫（CRUD / 匯入 / 刪除）
一般登入者 只能檢視框架 / 版本 / catalog

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

UC-CFM-01 管理框架版本並檢視 catalog

項目 內容
角色 platform admin（寫）/ 任一登入者（讀）
前置條件 已登入
產出 / 後置條件 框架 / 版本 CRUD；版本詳情載入 catalog 樹；published 版本鎖刪除
uc_cfm_01 start list 框架清單 → 點框架名稱 進版本管理（POST /oscal-framework-versions） start->list admin FE：是 platform admin？ （決定建立/編輯/刪除鈕） list->admin ro 唯讀檢視版本 / catalog admin->ro 否 act 建立 / 編輯 / 匯入版本 / 刪除 （BE require_platform_admin） admin->act 是 view 版本有 catalog？ ro->view deny 403 GRC_403060 （僅平台 root 租戶管理員可編輯） act->deny BE 再驗失敗 act->view del publish_status = draft？ act->del 刪除 detail 版本詳情雙欄 GET .../{uid}/catalog-tree （左 PDF｜右控制項樹） view->detail 是 sub 無 catalog → 進子版本清單 view->sub 否 ok 操作成功（重查清單） detail->ok nodel published 不可刪（鈕隱藏） del->nodel 否 del->ok 是
UC-CFM-01 流程：框架→版本→依 platform admin 決定可寫→版本有 catalog 開詳情、無則子版本→draft 才可刪

UC-CFM-02 框架批次刪除

項目 內容
角色 platform admin
前置條件 已登入；於框架清單多選（FE 僅對 draft 列提供 checkbox / 自動濾非 draft）
產出 / 後置條件 選集中的 draft 框架刪除；published 不納入；非 platform admin → GRC_403060
uc_cfm_02 start admin FE：是 platform admin？ （決定是否顯示 checkbox 欄 / 批次刪除鈕） start->admin hide 非 platform admin：不顯示批次刪除 admin->hide 否 sel 多選框架列 → 點批次刪除 admin->sel 是 filter FE 自動濾掉非 draft 列 （published 不納入刪除集） sel->filter empty 濾後無可刪列 → 不動作 filter->empty 全非 draft call DELETE /oscal-framework （僅送 draft 框架 uid） filter->call 有 draft guard BE require_platform_admin？ ＋ draft 檢查 call->guard deny 403 GRC_403060 （僅平台 root 租戶管理員可刪） guard->deny 否 ok 批次刪除成功（重查框架清單） guard->ok 是
UC-CFM-02 流程：platform admin 才顯示批次刪除→多選→FE 自動濾非 draft→DELETE /oscal-framework（僅 draft）→BE require_platform_admin ＋ draft 檢查→成功重查清單

UC-CFM-03 下載版本 catalog 為 OSCAL JSON

項目 內容
角色 任一取得下載連結者（端點無 JWT，uid 當憑證）
前置條件 版本已關聯 catalog（catalog_id）；取得版本 uid
產出 / 後置條件 無寫入；回傳該版本 catalog 的 OSCAL JSON 供瀏覽器下載
uc_cfm_03 start pick 版本清單 → 選一個已關聯 catalog 的版本 start->pick click 點 OSCAL 下載連結 （帶版本 uid） pick->click call GET /oscal-framework-version/download/oscal/{uid} click->call auth 端點無 @jwt_required uid 即憑證（unguessable） call->auth build 組出版本 catalog 的 OSCAL JSON auth->build uid 命中 file 瀏覽器下載 OSCAL JSON 檔（唯讀匯出，不改資料） build->file
UC-CFM-03 流程：選有 catalog 的版本→點 OSCAL 下載→GET /oscal-framework-version/download/oscal/{uid}（無 @jwt_required、uid 憑證）→組 OSCAL JSON→瀏覽器下載

3. 權限矩陣

操作 FE 判定 BE 強制 BE 檢查位置
讀框架 / 版本 / catalog 登入即可 JWT route @jwt_required()
框架 CRUD isPlatformAdmin（userStore） require_platform_admin()（_session_paths_have_root）→ GRC_403060 common/util/permission.py:28；app/oscal/service/framework_app_service.py（add/update/delete_framework）
版本 CRUD / 匯入 isPlatformAdmin require_platform_admin() → GRC_403060 framework_app_service.py（import_framework_version 等）
刪除框架 / 版本 draft-only（FE 隱藏 + 自動濾）+ isPlatformAdmin 同上 + draft 檢查 同上
OSCAL 下載 連結 無 @jwt_required，以 uuid 為憑證（unguessable uid） download route

⚠️ OSCAL 下載端點無 JWT、靠 uid 不可猜當憑證——屬設計取捨（公開匯出），但 uid 外洩即可下載，維護時留意。

4. 狀態機與前置條件

發布生命週期見 _overview §3。本頁 gate：

條件 效果 出處
publish_status = 'draft' 可刪除 / 編輯內容 FE 自動濾 + BE draft 檢查
publish_status = 'published' 鎖刪除（鈕隱藏）；仍可改 status 同上
版本有 catalog_id 名稱連結 → 詳情雙欄；否則 → 子版本清單 onVersionLinkClick
框架版本 ↔︎ catalog 1:1，catalog 由匯入回填 catalog_id framework_versions.catalog_id

5. UI 設計

版面骨架（兩頁）：

頁 1：框架清單（ComplianceFrameworkManage）— 🔍 搜尋 name/code/authority ＋重設 開啟：UC-CFM-01 管理框架版本並檢視 catalog 框架清單（CMMC 2.0／ISO27001…）＋ 建立／編輯／刪除（draft-only） 框架名稱連結 → 頁2 版本管理；欄位：main_version / authority / publish_status POST /oscal-frameworks（清單）・GET/POST/PUT/DELETE /oscal-framework[/{uid}] → UC-CFM-01（點我開啟） 開啟：UC-CFM-02 框架批次刪除 框架批次刪除 — platform admin 才顯示，多選（FE 自動濾非 draft） DELETE /oscal-framework（僅 draft）→ require_platform_admin，GRC_403060 → UC-CFM-02（點我開啟） 頁 2：版本管理（ComplianceFrameworkVersionManage，per 框架）— 🔍 搜尋＋建立版本／匯入版本 開啟：UC-CFM-01 管理框架版本並檢視 catalog 版本清單（version/release_date/publish_status）＋ CRUD ＋ 匯入版本 ＋ 子版本巢狀 POST /oscal-framework-versions（清單）・GET/POST/PUT/DELETE /oscal-framework-version[/{uid}] GET /oscal-framework-version/{uid}/catalog-tree → UC-CFM-01（點我開啟）；匯入版本另見 compliance-framework-import-version.md Dialog：版本詳情雙欄（左 PDF iframe｜右 catalog 樹：群組→控制項→AO/指引） 有 catalog_id → 開詳情；無 → 子版本清單（parent_id 巢狀） 開啟：UC-CFM-03 下載版本 catalog 為 OSCAL JSON OSCAL 下載 — GET /oscal-framework-version/download/oscal/{uid}（無 JWT，uid 憑證） → UC-CFM-03（點我開啟） 彩色＝可點跳本頁 §6/UC，灰＝本頁結構｜虛線＝dialog／條件顯示層 API 僅列代表性 2~3 條，完整規格見 §6
框架管理版面：頁1 框架清單 CRUD + 批次刪除、頁2 版本清單 + 版本詳情雙欄 + OSCAL 下載；可點跳 UC-CFM-01/02/03

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

框架清單：CMMC 框架列（版號/發布機關/發布狀態/描述）

版本清單：CMMC Level 1 / Level 2 / 2.13 Level 1 三版本

版本詳情雙欄：右欄 catalog 樹（Access Control 群組 4 項控制）；左欄 PDF 預覽因此版本未關聯來源 PDF 而空白（真實資料狀態）

狀態呈現：publish_status 經 transPublishStatusDesc i18n；platform admin 才顯示建立 / 匯入 / 批次刪除 / checkbox 欄；版本詳情用雙欄（左 PDF iframe、右 catalog 樹 accordion）。

6. API 規格

Envelope：成功 {"status": true, "data": …, "meta": …}（清單帶分頁）、失敗 {"error_code": "…", "msg": "…"}。

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

分類 Method + Path 說明 完整規格
框架 POST /oscal-frameworks 框架分頁清單 §6.2
框架 GET /oscal-frameworks/menu publish_status 選單 GAI-SD-02
框架 GET/POST/PUT/DELETE /oscal-framework[/{uid}] 框架讀 / 建 / 改 / 刪 §6.2
版本 POST /oscal-framework-versions 版本分頁清單（filters framework_uid / is_root / parent） §6.2
版本 GET/POST/PUT/DELETE /oscal-framework-version[/{uid}] 版本讀 / 建 / 改 / 刪 §6.2
版本 GET /oscal-framework-version/{uid}/catalog-tree 版本 catalog 詳情樹 §6.2
版本 GET /oscal-framework-version/download/oscal/{uid} OSCAL JSON 下載（無 JWT，uid 憑證） GAI-SD-02
匯入 POST /oscal/framework-versions/import 從檔案匯入版本（→ import-version 頁） import-version

6.2 核心 endpoint

[POST] /oscal-frameworks（框架清單）

Request：

欄位 型別 必填 說明
pager object 否 分頁（{page, page_size, with_total}）
sorts array 否 排序條件
filters object 否 篩選：name / code / authority / publish_status

Response data[]：框架物件（陣列，每項）+ meta 分頁。

欄位 型別 說明
uid string 框架 uid
name string 框架名稱
code string 框架代碼
main_version string 主版本標籤
authority string 發布機關
publish_status string 發布狀態
description string 描述

組裝在 Python 層過濾分頁（app/oscal/service/framework_app_service.py::get_frameworks_and_pager）。出處：api/oscal/routes/framework/oscal_framework_route.py::OscalFrameworksRoute.post

[POST] /oscal-framework-versions（版本清單）

Request：

欄位 型別 必填 說明
pager object 否 分頁（{page, page_size, with_total}）
sorts array 否 排序條件
filters object 否 篩選：framework_uid、is_root=true 或 parent_version_uid、version / publish_status

Response data[]：版本物件（陣列，每項）。

欄位 型別 說明
uid string 版本 uid
framework_id int 所屬框架 id
version string 版本標籤
release_date date 發行日
publish_status string 發布狀態
parent_id int｜null 版本血緣 self-FK（子版本），NULL = 首版
catalog_id int 對應 catalog id（1:1）

出處：同群 route。

[GET] /oscal-framework-version/{uid}/catalog-tree

Response data：扁平結構（FE 自行重組巢狀 accordion）。

欄位 型別 說明
groups array 控制項群組
controls array 控制項
assessments array AO / 評估指引

出處：api/oscal/routes/framework/...

寫入類（框架 / 版本 CRUD）

框架 POST/PUT body：

欄位 型別 必填 說明
name string 是 框架名稱
main_version string 是 主版本標籤
authority string 是 發布機關
publish_status string 是 發布狀態（draft / published）
description string 否 描述
code string 是 框架代碼

版本 POST/PUT body：

欄位 型別 必填 說明
framework_uid string 是 所屬框架 uid
version string 是 版本標籤
release_date date 是 發行日（%Y-%m-%d）
publish_status string 是 發布狀態（draft / published）
parent_version_uid string 否 父版本 uid（子版本用）

全部 require_platform_admin() → GRC_403060。出處：app/oscal/service/framework_app_service.py

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

檔案 角色
src/views/compliance-framework/ComplianceFrameworkManage.vue 頁1 框架清單 CRUD
src/views/compliance-framework/ComplianceFrameworkVersionManage.vue 頁2 版本清單 / 詳情 / 匯入入口
src/config/router/index.js:523-555 routes compliance-framework-manage / -version-manage
src/config/api/api.js endpoint 常數（OSCAL_FRAMEWORK* 等）
src/config/locales/i18n/zh-tw/compliance-framework-manage.json 頁面 i18n

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

鏈路 Route App Service 底層
框架清單 api/oscal/routes/framework/oscal_framework_route.py::OscalFrameworksRoute.post app/oscal/service/framework_app_service.py::get_frameworks_and_pager（Python 層過濾分頁） jedi_oscal_v2 FrameworkService.list_frameworks
框架 CRUD 同檔 OscalFrameworkRoute add/update/delete_framework（require_platform_admin） jedi_oscal_v2 FrameworkService
版本 / 匯入 oscal_framework_version_route.py / oscal_import_route.py framework_app_service（version CRUD / import_framework_version → catalog_service.import_catalog_from_{pdf,excel}） jedi_oscal_v2 CatalogService
catalog 樹 version route catalog-tree catalog tree service catalog repos

DDD 提醒：框架 / 版本寫入一律 require_platform_admin()；OSCAL 下載無 JWT 是刻意公開端點，別比照。

9. DB

9.1 資料表總清單

表 讀/寫 說明 欄位詳述
oscal.frameworks 讀 / 寫 框架主檔 §9.3
oscal.framework_versions 讀 / 寫 框架版本（catalog 1:1、子版本血緣） §9.3
oscal.catalogs 讀（匯入寫） 版本 catalog 根（匯入生成） GAI-SD-03
oscal.catalog_groups / catalog_controls / catalog_control_parts 讀 控制項三層 + AO（catalog 詳情） GAI-SD-03

9.2 ER 圖

cfm_er fw oscal.frameworks uid / name / code main_version / authority publish_status ver oscal.framework_versions framework_id / version release_date / publish_status parent_id（子版本血緣） catalog_id（1:1） fw->ver 1:N framework_id ver->ver parent_id 子版本 cat oscal.catalogs 控制項全集根 （匯入生成） ver->cat 1:1 catalog_id grp oscal.catalog_groups → catalog_controls → catalog_control_parts 三層 + AO part （catalog-tree 詳情） cat->grp 1:N
框架→版本→catalog：framework_versions.catalog_id 1:1、parent_id 子版本血緣

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

oscal.frameworks — 合規框架主檔

uid / name / code（如 CMMC_2）/ main_version（字串標籤，非 FK）/ authority / publish_status / description。框架是傘、版本才掛 catalog。

oscal.framework_versions — 框架版本

欄位 型別 說明
framework_id bigint → oscal.frameworks.id
version / release_date varchar / date 版本標籤 / 發行日
catalog_id bigint → oscal.catalogs.id（1:1，匯入後回填）
parent_id bigint｜null 版本血緣 self-FK（子版本，如 L1.5 掛 L1）；NULL = 首版
publish_status varchar(20) 產品生命週期；資源庫只能選 published（FR-038 §42）

10. 頁面邏輯與資料對應

載入：頁1 POST /oscal-frameworks；點框架名稱 → 頁2 POST /oscal-framework-versions（帶 framework_uid）；點版本 → 有 catalog 開詳情（GET catalog-tree）、無則子版本清單。

關鍵欄位對應：

畫面元素 API 欄位
框架清單列 frameworks {name, main_version, authority, publish_status}
版本清單列 versions {version, release_date, publish_status, catalog_id}
版本詳情樹 catalog-tree {groups, controls, assessments}（扁平重組）

錯誤對應：寫入非 platform admin → GRC_403060；其餘常規 CRUD 錯誤。

11. 背景行為與外部依賴

類型 內容
匯入解析 版本匯入走 catalog 解析（PDF/Excel），見 import-version 與 _overview §4
Socket 本頁無 socket
jedi-* 套件 jedi-oscal-v2（Framework / Catalog service）、jedi-auth（JWT / platform admin 判定）
系統參數 無 feature flag

12. 邊界情況與已知坑

  1. 框架 ↔︎ 版本 ↔︎ catalog 1:1:1：版本掛一份 catalog（catalog_id）；main_version 是框架上的字串標籤不是 FK（2026-06-16 移除自動首版）
  2. 版本雙模式連結：有 catalog → 詳情雙欄；無 catalog → 子版本清單（parent_id 巢狀）；點連結行為依此分流
  3. published 鎖刪除：FE 隱藏 + 多選自動濾 draft；BE draft 檢查。published 版本不可刪但可改 status
  4. catalog-tree 扁平回傳：{groups, controls, assessments} 扁平，FE 自行重組 accordion；本頁無 catalog 寫入 UI（內容編輯另有 article-edit route）
  5. OSCAL 下載無 JWT：uid 當憑證，外洩即可下載
  6. 框架是全域資源：僅 platform（root 租戶）admin 可寫；一般租戶管理員也不行（GRC_403060）

13. 開發與驗證

  • 跑起來：BE python main_socketio.py（port 8000，log 在 log/app.log）；FE Vite dev server。BE 改 service code 必重啟
  • 測試帳號：需 platform（root 租戶）admin 帳號才能驗寫入；一般帳號驗唯讀（密碼見 .env / 部署文件）
  • 導航路徑：側邊選單「合規框架管理」→ 點框架 → 版本管理
  • 前置資料：至少一個框架 + 版本 + 匯入的 catalog 才看得到詳情
  • E2E：compliance-manager-test/ repo；以 合規框架 / framework 搜尋
  • 相關文件：版本匯入 import-version、資源庫 module-frame、資產模型 _overview
Guidant AI 功能 SPEC 手冊 v1.8.0｜本頁由 render_html.py 產生，內容源：specs/v1.8.0/compliance-framework/compliance-framework-manage.md