🟢 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。

根本處境：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 改走什麼？④ 專案/稽核為何是另一條大重構、計畫在哪？

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

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 舊引擎漸進退場。

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

• 框架路由全在舊 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）。

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 派工）。

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

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 實測」）。

• 不切 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。

• 專案/稽核 audit-round 重構（另一條大棒，照 migration-plan，FE 重寫量大）。
• AO 欄位修正（user 另 session 派工）。
• BE 退版 / FE 退版（已確認不做）。
• stg/poc/prod migration、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）。

讀 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 實點。