# 🟢 START HERE — FR-038 前端套用「重新規劃」交接（框架已分析、資源庫已分析、專案待重構）

> **給下個 session 的 prompt**：「讀本檔，先過『🧭 WHY』+ §0 讀序,能答冷接自檢再動。這不是 bug-fix 棒,是『把 FE 逐項套到 FR-038 v2 BE』的重新規劃 arc。框架/資源庫的 v1↔v2 比對已完成(見比對文件),接手做：(a) 依 user 決策細化資源庫遷移步驟 (b) 或回答『FE 要送什麼 payload 更新』。」
> 本檔自包含。狀態 **2026-06-16**。

## 🧭 WHY：這 arc 在解什麼（先懂才動）

**根本處境**：FR-038 把 BE 整個翻成 jedi_oscal_v2（Wave 2A 地基翻轉 + 2B 業務重接 v2）。但 **FE 停在 06-08（v1.4.0），從沒跟上**。所以「重啟新 BE 後拿舊 FE 點 → 大面積壞」是**預期內**（BE 變了、FE 沒跟上），**不是 FE 被改壞**。

**已釐清的關鍵事實（別再誤判）**：
- **FE 無退版可退**：FE repo 所有 branch + stash + working tree，06-09 後**零 commit**，乾淨停在 06-08。曾要求「退 FE 版」→ 沒東西可退（它就是基準）。
- **不退 BE**：user 2026-06-16 拍板 **「BE 維持 v2，FE 以 06-08 為基準逐項套上去」**。
- 所以本 arc = **逐功能比對 v1 FE ↔ v2 BE，規劃 FE 怎麼套**。專案/稽核那塊是大重構（另有遷移計畫）；框架小、資源庫中。

**目標模型**（FR-038 v2，必懂）：framework→framework_version→catalog 三層；資源庫=clone catalog+profile+**範本SSP**三件組；稽核以 **audit-round 輪次**為核心（engagement 模型）。

> **冷接自檢 4 問**（答不出回 §0）：① 為何「FE 套上去不能用」、為何不是退 FE 版能解？② 框架為何「大致可直接套用」、資源庫為何「需重構」？③ 資源庫的「適用控制項編輯」v2 改走什麼？④ 專案/稽核為何是另一條大重構、計畫在哪？

## §0 接手讀序（按序）

1. 本檔「🧭 WHY」+ 通讀
2. 🔒 **全 FE 套用比對表**（總覽）：[`fe-apply-comparison.md`](../fe-apply-comparison.md)
3. 🔒 **框架 v1↔v2 比對**：[`fe-framework-v1-v2-comparison.md`](../fe-framework-v1-v2-comparison.md)
4. 🔒 **資源庫 v1↔v2 比對**：[`fe-resource-library-v1-v2-comparison.md`](../fe-resource-library-v1-v2-comparison.md)
5. **專案/稽核遷移計畫**（另一條大重構）：[`audit-round-fe-migration-plan.md`](../audit-round-fe-migration-plan.md)
6. **API 全清單**：[`fr038-api-inventory.md`](../fr038-api-inventory.md)
7. **框架維護變更帳 + 驗證缺口**：[`2026-06-16-framework-maintenance-change-accounting.md`](2026-06-16-framework-maintenance-change-accounting.md)
8. 框架維護決策：[`docs/analysis/2026-06-16-framework-maintenance-2a2b-decisions.md`](../../../analysis/2026-06-16-framework-maintenance-2a2b-decisions.md)

## §1 三大功能現況（本 arc 的「症狀」= 套用落差）

### 1.1 合規框架 → 大致可直接套用（小改）
- BE：framework維護 2a/2b 我已重建 v2 + **註冊回舊 URL**（CRUD/版本/catalog 編輯/兩階段匯入全在舊 URL）。
- **要修（小）**：**AO 欄位對映** —— FE 讀寫 `assessment.description`，但 v2 adapter 把 AO 文字（part.prose）掛在 `name`、description=None。影響 catalog 編輯/匯入預覽/版本詳情三處 AO 顯示空。
  - **user 決策（2026-06-16）**：照 v2 模式，**改 FE 讀 v2 欄位**（不是 BE 假裝舊 shape）。**先別修**，user 手測後另開 session 派工。
  - 真實一筆例子：v2 `catalog_control_parts` id=8412 → `prose='[a] authorized users are identified'`、`title=NULL`、`name='assessment-objective'`(鑑別子)。
- 其餘小破口（版本詳情 catalog 內容預覽走另呼 tree、PDF file_uid 回填、舊匯入入口導兩階段頁、下載端點）見框架比對文件 §要修的點。

### 1.2 合規資源庫 → 中型重構（不是直接套用）
- **舊模型 STUBBED**：`module_frame_repo_impl._enrich_with_oscal`（2A 拔 jedi_oscal）→ 列表/詳情讀的 `oscal_profile.include_groups` / `oscal_framework_version.framework.name` **全空**；`control_default_service` / `objective_default_service` **回 None**（範本「適用控制項」編輯死的）。
- **典範轉移**：v2 廢「control-defaults/objective-defaults 範本預設值」→ 改「資源庫帶範本 SSP（template_ssp_id），用 SSP 維護的 control-implementation SoA 對 template_ssp_uid 編」。新建從 include_controls → `/oscal/resource-libraries` clone 三件組。
- **可重用**：範本編輯的 SSP 子表 tab（system-characteristic/components/leveraged/inventory/parties/程序書池）B3 已接 v2；SSP 匯入匯出接 v2。

### 1.3 專案 / 稽核 → 大重構（另一條，已有計畫）
- 雙軌並存：舊 `/grc/project/ap/*`（依賴**已退役表** assessment_plan_controls/tasks → 恐壞）vs 新 audit-round 引擎（`/audit-round/<id>/*`，B2~B5 已 v2，FE 未接）。
- 計畫見 `audit-round-fe-migration-plan.md`（5 step：Step0 地基→①輪次列表→②AP維護新建→③AR維護AO+risk→④POA&M三層）。決策 D1 路由改 roundUid、D2 舊引擎漸進退場。

## §2 前次教訓（別重蹈）

- **我過度宣稱「驗過/零回歸/FE 零改」** —— 只驗 `create_app()` DI + 隔離測路由 + service smoke + pytest，**沒跑完整 `main_app.py`、沒對真實 FE 測**。導致 framework維護宣稱「FE 零改可用」但實際 AO 等欄位對不上。**接手做任何「能用」判定前,務必對真實運行 FE 實點,別憑 service smoke 下結論。**
- AO 欄位踩過：FE 一路讀 `description`，v2 我對映成 `name` → 三畫面 AO 空白。比對表已標。

## §3 v2 BE 現況硬事實（已驗，可信）

- 框架路由全在舊 URL（已 boot + url_map 驗）：`/oscal-frameworks`、`/oscal-framework[/<uid>]`、`/oscal-framework-version[s]`、`/oscal-framework-parse-jobs/*`、`/oscal-catalog-{group,control,control-assessment}/<uid>`。
- 資源庫 stubbed：`grep -n _enrich infra/module_frame/repository/module_frame_repo_impl.py`（見 `disabled`）；`grep jedi_oscal app/module_frame/service/module_frame_control_default_service.py`（import 註解掉、回 None）。
- 未註冊：`/oscal/catalog-controls/<uid>/assessments`、`/module-frame/<uid>/template-ssp`。
- 新資源庫端點：`/oscal/resource-libraries[/list]`、`/oscal/resource-library/<uid>[/publish]`（B1，回 catalog_uid/profile_uid/ssp_template_uid/resolved_control_count）。

## §4 接手開工順位

1. pre-flight（§6）+ 確認現況。
2. **等 user 回三個資源庫決策**（§下方「待決策」）後，把資源庫遷移細化成像框架那樣的「逐端點 + payload」步驟。
3. 若 user 問「FE 要送什麼 payload 更新」→ 直接讀對應 v2 route 的 request schema / service 簽章給出實際 payload（框架 AO 寫入：`PUT /oscal-catalog-control-assessment/<id>` body 應改吃 `{description}`→寫 part.prose；目前 code 吃 `{name}`，這也是要改的點）。
4. **不要 implicit 修 AO**（user 說先別修、另 session 派工）。

## §5 待決策（user 尚未回 — 資源庫遷移方向）

1. 「適用控制項編輯」確定改走「編範本 SSP 的 control-implementation SoA」?（取代 control-defaults/objective-defaults）
2. 列表/詳情「框架名/控制數」改從新 resource-library 端點取（`resolved_control_count` 等）?
3. control-defaults 的 Excel 匯入匯出還要保留嗎?（整套依賴已廢 service）

## §6 Pre-flight（必跑）
```bash
cd /Users/chouraymond/Projects/Billows/Audit-Manager/compliance-manager-be
git branch --show-current            # feature/oscal-refactor（不可切 branch）
git status --short                    # 應僅 M pyproject.toml（dev path-dep 勿 commit）
cd ~/Projects/Billows/Audit-Manager/compliance-manager-fe && git log -1 --format='%h %ad' --date=short  # fc883ca 2026-06-08（FE 基準）
```
> ⚠️ DB 環境疑慮：曾見我腳本連的 DB 報 `frameworks.main_version` 不存在、但 188/guidant_ai_dev 有該欄 + 已有 commit `a190befe` 補字串欄。接手若要對 BE 實測，先確認 `.env` 的 `DB_HOST`/`DB_NAME` 指向哪、schema 是否跟上 model（這條跟 FE 套用獨立，但會影響「BE 實測」）。

## §7 行為規範
- **不切 branch**；**push / 套件發 Nexus 等 user 明示**；`pyproject.toml` dev path-dep 勿 commit。
- 跨 repo（FE）動工前先讀 FE CLAUDE.md（646 行）。
- 改 BE 後提醒 user 重啟；服務 user 自己起（不附啟動命令）。
- 任何「能用」判定要對真實 FE 實點，別只憑 service smoke（§2 教訓）。
- 不晶晶體；plan 假設先 verify。

## §8 不在本 arc scope（別順手做）
- 專案/稽核 audit-round 重構（另一條大棒，照 migration-plan，FE 重寫量大）。
- AO 欄位修正（user 另 session 派工）。
- BE 退版 / FE 退版（已確認不做）。
- stg/poc/prod migration、push、套件發版。

## §9 本 arc commits / 文件（未 push）

**框架維護（BE，已 commit；我做的）**：框架 CRUD 接舊 URL + delete + 版本管理 2a + catalog 編輯 2b + 兩階段匯入 parse-job（接 v2）。**注意 git 已 rebase，我的原 hash 不在**；近期 HEAD 另有平行 session 的框架修正（`a190befe` main_version 字串欄 / `7a95b6bf` 不自動生版本 / `2352ee20` 移除 code unique）+ 止血（`e5fac369`/`742ba3f3` flow-engine/SSP，非框架）。
**套件（jedi-oscal-v2，dev path-dep 未發版）**：FrameworkService delete/version CRUD + framework_versions.release_date + delete_framework CASCADE + `93d1a45` main_version 字串欄。
**本 session 產出文件**：5 份（fe-apply-comparison / fe-framework-v1-v2-comparison / fe-resource-library-v1-v2-comparison / audit-round-fe-migration-plan / fr038-api-inventory）+ change-accounting + framework 驗收報告 + decisions。其中 **fe-framework-v1-v2-comparison.md / fe-resource-library-v1-v2-comparison.md 仍 untracked**（本次交接一併 commit）。

## §10 超短 prompt（給 fresh session）
```
讀 docs/features/FR-038-2606-oscal-redesign/handoff/2026-06-16-fe-apply-replanning-START-HERE-handoff.md。
先過 🧭 WHY + §0 讀序（4 份比對/計畫文件），能答冷接自檢 4 問（為何 FE 套不上不是退版能解 / 框架小改 vs 資源庫重構 / 適用控制項改編範本SSP / 專案另條大重構）才動。
這是「FE 逐項套到 v2 BE」的重新規劃 arc，非 bug-fix。BE 維持 v2、FE 06-08 為基準逐項套。
接手：等 user 回 §5 三個資源庫決策後細化資源庫遷移步驟；或回答「FE 要送什麼 payload 更新」（讀對應 v2 route schema）。
不切 branch、不 push、不 implicit 修 AO（另 session 派工）、能用判定要對真實 FE 實點。
```