合規框架管理（Compliance Framework Manage）¶
功能群：合規框架與 SSP｜資產模型與發布生命週期先讀 功能群總覽
事實基準：2026-07-05 從 FE / BE code 掃出；endpoint 對
routes.json、schema 對db_schema.json、error code 開檔驗。「AI 分類設定」分頁 2026-09-17 從套件jedi-evidence-classification與ComplianceFrameworkVersionManage.vue掃出（FR-107）變更紀錄： - 2026-09-17（FR-107）：版本管理頁新增「AI 分類設定」分頁——per 租戶 × 框架版本的 AI 角色 / 判斷指引 / 證據提示與模型預設值，四層由精確到通用退路。守門軸與框架版本寫入不同：框架版本是全域資源只有平台管理員能寫，分類設定是租戶級的（走
storage-config.update能力點）；AI 供應商金鑰不在本頁，鎖在系統設定另一頁只給 ROOT 平台管理員。見 §1.1（12）與 §3
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 |
| 12 | AI 分類設定（分頁） | 證據自動分類要用的 AI 角色 / 判斷指引 / 證據提示 ＋ 預設模型與信心門檻；per 租戶 × 框架版本，可停用（＝改用上一層而非關掉分類） | 頁2 第二個分頁（限有 storage-config.update 能力者可見） |
§1.2 |
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，於此只交叉連結不重複；AI 分類設定（12）的分類流程本身屬證據管理功能群，本頁只管這份設定的維護。
1.2 AI 分類設定分頁¶
證據自動分類要「換一個合規框架就換一組 AI 講法」，那組講法存在資料裡而不是寫死在程式碼——要支援新框架是新增一筆設定，不是改程式。
欄位：
| 欄位 | 說明 |
|---|---|
| 設定名稱 | 顯示用 |
| 適用範圍 | 通用（所有框架版本）／本框架版本；帶版本進來時預設綁該版本 |
| AI 角色（必填） | 告訴 AI 它是誰（例如「你是 ISO 27001 稽核員」），放在每次分類的最前面 |
| 判斷指引 | 怎麼判、什麼算有效證據、拿不定時怎麼辦 |
| 證據提示（JSON） | 針對特定檢查點給的提示，格式是「檢查點代號 → 提示字串陣列」 |
| 預設模型 | 跑分類時沒另外指定就用這個；留空＝由系統挑 |
| 預設信心門檻 | 低於此信心的判定留給人工確認（0~1，常用 0.7） |
| 預設思考深度 | 低／中／高三檔，預設中——控制模型花多少力氣推理。CM-1885 落地中 |
| 狀態 | 啟用／停用。停用不是關掉分類，是讓它改用上一層設定；資料留著可再啟用 |
四層退路（由精確到通用，逐層找到第一筆啟用的就用）：這個租戶 × 這個框架版本 → 出廠針對此版本 → 這個租戶的通用設定 → 出廠通用設定；全都落空才用系統內建的最小版（內建那份刻意不含任何框架名）。
可選模型清單是動態算的：該租戶已設定金鑰的供應商 × 系統支援的型號表取交集（GET /classification/available-models）。沒有任何金鑰時畫面顯示「目前沒有可用的模型」並給一個前往 AI 服務設定的連結，不列出選了才會 401 的型號。不支援讀圖的型號在選單上標明——遇到圖片證據會明確標「此模型不支援圖片，未分類」而不是靜默跳過（靜默跳過會讓使用者以為那張截圖被看過且判定為無關）。
🔴 出廠那份（ROOT 租戶）對業務租戶唯讀：清單上一起回是刻意的——使用者要看得到「我沒設定時系統實際會用什麼」，看不到的話「為什麼 AI 這樣講話」無從查起。改它回
EC_403004。🔴 金鑰不在這一頁。這裡只選「用哪家哪支模型」，金鑰本身鎖在系統設定另一頁、只有 ROOT 平台管理員能填，讀取時遮成「有沒有設定」的旗標、不回明文。
2. Use Case¶
角色速覽（本群非專案層角色，見 _overview §5）：
| 角色 | 一句話 |
|---|---|
| platform admin | 平台（root 租戶）管理員 — 唯一可寫（CRUD / 匯入 / 刪除） |
| 一般登入者 | 只能檢視框架 / 版本 / catalog |
流程圖視覺慣例：菱形 = 判斷、橘底 = 例外 / 擋下、紅框 = 錯誤（標 error code）、綠框 = 成功終點、虛線 = 可選路徑。
UC-CFM-01 管理框架版本並檢視 catalog¶
| 項目 | 內容 |
|---|---|
| 角色 | platform admin（寫）/ 任一登入者（讀） |
| 前置條件 | 已登入 |
| 產出 / 後置條件 | 框架 / 版本 CRUD；版本詳情載入 catalog 樹；published 版本鎖刪除 |
UC-CFM-02 框架批次刪除¶
| 項目 | 內容 |
|---|---|
| 角色 | platform admin |
| 前置條件 | 已登入；於框架清單多選（FE 僅對 draft 列提供 checkbox / 自動濾非 draft） |
| 產出 / 後置條件 | 選集中的 draft 框架刪除；published 不納入；非 platform admin → GRC_403060 |
UC-CFM-03 下載版本 catalog 為 OSCAL JSON¶
| 項目 | 內容 |
|---|---|
| 角色 | 任一取得下載連結者（端點無 JWT，uid 當憑證） |
| 前置條件 | 版本已關聯 catalog（catalog_id）；取得版本 uid |
| 產出 / 後置條件 | 無寫入；回傳該版本 catalog 的 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 |
| AI 分類設定 讀 | 分頁需 storage-config.update 能力 |
租戶管理員；跨租戶由 RLS 擋 | 套件 app/service/classification_profile_service.py |
| AI 分類設定 增改刪 | 同上 | 租戶管理員；改出廠那份 → EC_403004（唯讀） |
同上 _require_own_profile() |
| AI 供應商金鑰 | 不在本頁 | ROOT 平台管理員；讀取遮成 is_set 旗標、寫入加密後才落地 |
app/system_config/service/guarded_system_config_service.py |
⚠️ 分類設定與框架版本是兩條不同的守門軸，容易誤判：框架版本是全域共用資源（只有平台租戶能寫），分類設定是租戶級的（每個租戶各有自己的），所以用能力點而不是
isPlatformAdmin。把分類設定也鎖成平台管理員，等於所有客戶都不能自己調 AI 講法。⚠️ 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 設計¶
版面骨架（兩頁）：
實機截圖（STG，亮色模式，2026-07-05，帳號 blsadmin）：
狀態呈現：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 |
| AI 分類設定 | GET /classification-profiles?framework_version_id=&include_generic= |
列設定（含 ROOT 出廠那份，標唯讀） | §1.2 |
| AI 分類設定 | POST /classification-profiles |
建設定；同一框架版本已有設定回 EC_409006 |
§1.2 |
| AI 分類設定 | PUT/DELETE /classification-profiles/{profile_uid} |
改 / 刪；改出廠那份回 EC_403004 |
§1.2 |
| AI 分類設定 | GET /classification/available-models |
該租戶可用的模型＝已設金鑰的供應商 × 型號表交集 | §1.2 |
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 |
| compliance.classification_profiles | 讀 / 寫 | AI 分類設定（per 租戶 × 框架版本；tenant_id=1 是出廠通用那份）。軟參照 oscal.framework_versions.id、刻意不建 FK——那張表屬另一支插件，插件之間互不相依 |
證據管理 §6 |
9.2 ER 圖¶
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. 邊界情況與已知坑¶
- 框架 ↔ 版本 ↔ catalog 1:1:1：版本掛一份 catalog（
catalog_id）；main_version是框架上的字串標籤不是 FK（2026-06-16 移除自動首版） - 版本雙模式連結：有 catalog → 詳情雙欄；無 catalog → 子版本清單（
parent_id巢狀）；點連結行為依此分流 - published 鎖刪除：FE 隱藏 + 多選自動濾 draft；BE draft 檢查。published 版本不可刪但可改 status
- catalog-tree 扁平回傳：
{groups, controls, assessments}扁平，FE 自行重組 accordion；本頁無 catalog 寫入 UI（內容編輯另有 article-edit route） - OSCAL 下載無 JWT：uid 當憑證，外洩即可下載
- 框架是全域資源：僅 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