框架版本匯入 / 編輯（Framework Version Import / Edit）

功能群：合規框架與 SSP｜匯入三步式先讀 _overview §4、母頁 compliance-framework-manage

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

1. 功能描述

框架版本匯入 / 編輯是把框架版本的控制項全集從 PDF/OSCAL 匯入成 catalog、並編輯 catalog 內容的頁面。兩個相連頁面：

• 匯入頁（FrameworkImportPage.vue，2 route：/import-version 上傳、/import-version/:parseUid 預覽）：走 parse→預覽→confirm 三步式（見 _overview §4），confirm 後寫 oscal.catalogs + 回填版本 catalog_id。
• 版本內容編輯頁（FrameworkVersionEditView.vue）：對已匯入 catalog 的群組 / 控制項 / AO 做內嵌編輯（直接 PUT/DELETE，無暫存）。

主要使用者：平台（root 租戶）管理員（框架是全域資源）。

角色速覽（本群非專案層角色，見 _overview §5）：僅 platform admin 可匯入 / 編輯。

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

UC（§2）展開本頁所有具實質後端邏輯的功能：PDF 匯入三步（UC-CFI-01）、版本內容內嵌編輯（UC-CFI-02，與匯入不同機制、無暫存 diff）。草稿橫幅 / 失敗態 / 丟棄等純顯示或單步操作見 §6.1 / §10；replace-mode 等匯入變體併入 UC-CFI-01。

2. Use Case

角色速覽（本群非專案層角色，見 _overview §5）：僅 platform admin 可匯入 / 編輯。

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

UC-CFI-01 從 PDF 匯入框架版本控制集

UC-CFI-02 版本內容內嵌編輯（catalog 群組 / 控制項 / AO）

3. 權限矩陣

4. 狀態機與前置條件

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

5. UI 設計

📸 實機截圖三張皆從缺：本頁「新增/匯入版本」入口與本 route 都受 isPlatformAdmin 守門（ComplianceFrameworkVersionManage.vue::isPlatformAdmin——作用中租戶 path 為單層 /N/ 才算 root/平台租戶；合規框架屬全域資源，讀＝所有租戶、寫＝僅平台租戶）。2026-07-05 盤點：現有 E2E 測試帳號（blsadmin 等）所屬租戶皆非平台 root 租戶，直接打 route 也會被導回列表頁，暫無可用帳號截圖；待有平台租戶帳號再補。

版面骨架：

狀態呈現：兩步分屬兩 route（reload 可復原）；預覽用 Splitter（PDF 40% / 內容 60%）；編輯頁直接 PUT/DELETE 內嵌（無暫存 diff）。

6. API 規格

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

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

6.2 核心 endpoint

[POST] /oscal-framework-parse-jobs/parse

Request（multipart）：

Response data：{parse_uid, status}。出處：api/oscal/routes/framework/...parse_jobs

[GET] /oscal-framework-parse-jobs/{uid}

Response data：

狀態 awaiting_review / failed / confirmed。

[POST] /oscal-framework-parse-jobs/{uid}/confirm

Request：

confirm 後寫 oscal.catalogs + 回填 framework_versions.catalog_id。require_platform_admin → GRC_403060。出處：app/oscal/service/framework_app_service.py

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

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

DDD 提醒：匯入走三步式（暫存 parse job → confirm 才入正式表）；全程 require_platform_admin。

9. DB

9.1 資料表總清單

9.2 ER 圖

框架 → 版本 → catalog 結構見 compliance-framework-manage §9.2；本頁另寫暫存 oscal.framework_parse_jobs（confirm 後落地 catalog）。

9.3 核心表

oscal.framework_parse_jobs — 框架解析暫存 job

uid / status（awaiting_review / failed / confirmed）/ parsed_result（JSON 解析結果）/ target_framework_uid / parser_type / created_at / created_user。confirm 後結果落地正式 catalog；DELETE 放棄。

10. 頁面邏輯與資料對應

載入：Step1 GET 草稿清單；上傳 POST parse → 導向 Step2（/:parseUid）；Step2 GET 解析結果 → 預覽 → confirm。

關鍵欄位對應：

錯誤對應：非 platform admin GRC_403060；解析失敗 → 失敗態 error_code + 重試。

11. 背景行為與外部依賴

12. 邊界情況與已知坑

1. 三步式暫存：上傳解析成 framework_parse_jobs 暫存，confirm 才寫正式 catalog；未 confirm 可 DELETE 丟棄；草稿橫幅可續作
2. 兩 route 分步：/import-version（上傳）與 /import-version/:parseUid（預覽）分屬兩 route，reload 可復原、可分享連結
3. replace-mode：target_version_uid 已設時 metadata tab 隱藏、沿用既有版本 metadata；confirm 不送新 metadata
4. 內容編輯無暫存：FrameworkVersionEditView 直接 PUT/DELETE 內嵌，非匯入的暫存 diff——與匯入頁不同機制
5. 編輯 gate：版本非 draft 或非 platform admin → 唯讀；有引用（has_references）才可刪控制項
6. platform admin only：框架全域資源，一般租戶 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 / 部署文件
• 導航路徑：合規框架管理 → 版本管理 → 匯入版本
• 前置資料：一個框架；一份 PDF 控制集檔案
• E2E：compliance-manager-test/ repo；以 框架匯入 / framework-import 搜尋
• 相關文件：母頁 compliance-framework-manage、匯入三步式 _overview §4