# 合規框架 — v1 FE 流程 ↔ v2 BE 逐欄比對 + 遷移評估

> 目的：判斷現行 FE 框架 4 畫面能否直接吃 v2 BE，或要怎麼遷移。
> 方法：v1 FE 實際呼叫/讀寫欄位（FE code 盤點）↔ v2 BE adapter（framework維護工作我寫的）逐欄對照。
> **信心**：URL/欄位比對為客觀（已查 FE code + BE 註冊）；標 ⚠️ 者為需重啟後對真實 FE 複驗。

## 一句話結論

**框架 CRUD（畫面1）可直接套用、FE 零改；版本管理/匯入/catalog 編輯（畫面2~4）流程都接得上，但有 4 個具體對不上點要修 —— 多數是 BE adapter 小修，不是 FE 重寫。** 其中「AO 欄位對映」一處改就同時修好 3 個畫面。

---

## 畫面 1：框架 CRUD（ComplianceFrameworkManage）→ ✅ 直接套用

| FE 動作 | FE 端點 | v2 BE | 結果 |
|---------|---------|-------|------|
| 列表 | POST `/oscal-frameworks` | 已註冊舊 URL，回 uid/name/main_version/authority/publish_status/description | ✅ 欄位全對 |
| 新增 | POST `/oscal-framework` `{name,code,main_version,authority,publish_status,description}` | OscalFrameworkCreateRequestSchema 接受 | ✅ |
| 編輯 | PUT `/oscal-framework/<uid>` | ✅ | ✅ |
| 刪除 | DELETE `/oscal-framework/<uid>` | 我補了 delete | ✅ |

**→ FE 零改動可用。**（仍需重啟後實點確認）

## 畫面 2：版本管理（ComplianceFrameworkVersionManage）→ 🔧 接得上，4 點要修

| FE 動作 | FE 端點 | v2 BE 現況 | 結果 |
|---------|---------|-----------|------|
| 框架詳情 | GET `/oscal-framework/<uid>` | ✅ 註冊 | ✅ |
| 版本列表 | POST `/oscal-framework-versions`（filters: framework_uid / is_root / parent_version_uid）| adapter 回 version/release_date/publish_status/parent/children/is_root/parent_version_uid | ✅ 樹/欄位對 |
| 新增/編輯/刪除版本 | POST/PUT/DELETE `/oscal-framework-version[/<uid>]` | ✅ 註冊 + release_date 已支援 | ✅ |
| **❶ 版本詳情預覽** | 讀 `version.catalog.groups[].controls[].assessments[].description` | **adapter 只回 `catalog={uid,id}`、無內容** | 🟥 預覽空白 |
| **❷ PDF 預覽** | `version.file_uid` → `/file/pdf-preview/<uid>`，否則舊 `/oscal-framework-version/download/pdf/<uid>` | adapter 回 `file_uid=None`、舊下載端點**未註冊** | 🟥 預覽/下載壞 |
| **❸ 此頁匯入版本** | POST `/oscal-framework-version/import/<type>`（json blob）| **未註冊**（只有新 `/oscal/framework-versions/import`，shape 不同）| 🟥 此頁匯入鈕壞 |
| **❹ 下載 excel/oscal/sample** | `/oscal-framework-version/download/{excel,oscal,sample}/<uid>` | **未註冊** | 🟥 壞 |

## 畫面 3：兩階段 PDF 匯入（FrameworkImportPage）→ 🔧 流程接上，AO 欄位要修

| FE 動作 | FE 端點 | v2 BE | 結果 |
|---------|---------|-------|------|
| 草稿列表 / parse / detail / confirm / discard | `/oscal-framework-parse-jobs[...]` | ✅ 全註冊舊 URL | ✅ 流程接上 |
| **❺ AO 預覽/編輯** | FE 讀寫 `assessment.description`（`FrameworkArticleContent.vue:245,248`）| 我 `_tree_to_dict` 輸出 `name=prose, description=None`；confirm `_persist_catalog` 讀 `name` | 🟥 AO 文字不顯示 + 使用者編輯丟失 |
| confirm payload | `{decisions, overrides, target_version/release_date/publish_status}` | ✅ 接受 | ✅（除 AO override 走 description）|
| ⚠️ parse 上傳 | multipart file + json blob `{target_framework_uid, parser_type, ...}` | route 解析方式需複驗跟 FE 送法一致 | ⚠️ 待驗 |

## 畫面 4：catalog 編輯（FrameworkVersionEditView）→ 🔧 接得上，AO + 已知限制

| FE 動作 | FE 端點 | v2 BE | 結果 |
|---------|---------|-------|------|
| catalog-tree | GET `/oscal-framework-version/<uid>/catalog-tree` | adapter 回 flat groups/controls/assessments + group_uid/control_uid 連結 + has_references + publish_status | ✅ 結構對（flat，同舊）|
| 改/刪 group/control/AO | PUT/DELETE `/oscal-catalog-group\|control\|control-assessment/<uid>` | ✅ 註冊 | ✅ URL 對 |
| **❺ AO description** | FE 讀寫 `ao.description` | adapter `_flatten` 回 `name=prose, description=None`；`update_assessment` 寫 `prose←name` | 🟥 同畫面3 |
| **❻ group.description / control.guidance** | FE 顯示/編輯這兩欄 | v2 無對應欄 → 回 None、寫忽略（已知限制）| ⚠️ 顯示空、編輯不保存 |
| 重新上傳（覆蓋）| parse + `target_version_uid` | ✅ 我有支援 | ✅ |

---

## 要修的點（彙整，多數 BE adapter 小修）

| # | 問題 | 影響畫面 | 修法（建議）| 端 |
|---|------|---------|------|----|
| **❺ AO 欄位對映** | FE 讀寫 `assessment.description`，v2 adapter 放在 `name` | 2、3、4（一改三修）| adapter 把 AO 文字對映回 **description（↔ part.prose）**，寫入也 description→prose | **BE**（一處）|
| **❶ 版本詳情 catalog 內容** | list adapter 無 catalog 內容 | 2 | FE 改成點預覽時另呼 `catalog-tree`（輕）；或 BE list 補內容（重）| FE 優先 |
| **❷ PDF 預覽 / file_uid** | adapter file_uid=None + 舊下載端點未註冊 | 2 | parse-job 有存 file_path(=file_uid)，adapter 回填 version.file_uid → 走 `/file/pdf-preview`；或補舊下載端點 | BE |
| **❸ 此頁匯入** | 舊 `/oscal-framework-version/import/<type>` 未註冊 | 2 | 此頁匯入入口導去兩階段匯入頁（畫面3，已 live）即可，不必補舊端點 | FE |
| **❹ 下載 excel/oscal/sample** | 未註冊 | 2 | 評估是否還需要；要的話補 export 端點（B5 已有 `/oscal/export/<doc_type>/<uid>` 可借）| BE/FE |
| **❻ group.desc / control.guidance** | v2 無欄 | 2、4 | 決定：接受空白 / 或 v2 加 part 承載 | 決策 |

## 遷移結論

- **可直接套用**：畫面 1（框架 CRUD）。
- **小幅遷移即可**：畫面 2~4。核心是 **❺ AO 欄位對映（BE 一處改、修好 3 畫面）**，其餘是 catalog 預覽改走 tree 端點、PDF/下載端點補齊、匯入入口導向兩階段頁。**不需要 FE 重寫**，跟專案/稽核那種大重構不同。
- 「直接套用」前都需重啟 BE 對真實 FE 實點複驗（標 ⚠️ 處）。

## 建議下一步
1. 先修 ❺（AO 對映，BE adapter，一處改三畫面）—— 風險低、效益大。
2. 重啟 BE，實點畫面 1~4，把 ⚠️ 待驗翻成事實。
3. 依實點結果處理 ❶~❹。