FR-038 框架維護 2a/2b 再啟用 — 實作計畫

範圍：把 Wave 2A disable 的三組「框架維護」route 重寫接 v2、註冊回舊 URL、對齊舊 shape → FE 零改動。 上游決策：framework CRUD 已用此原則 ship（BE 路由接回 /oscal-frameworks*、/oscal-framework*，FE 未動）。 撰寫日：2026-06-16　branch：feature/oscal-refactor（BE + 套件）

1. FE 零改動：route 一律註冊回舊 URL（/oscal-framework-versions、/oscal-catalog-group …），主專案 app service 當 adapter 對齊舊 request/response shape。
2. 絕不 import v1 jedi_oscal 進 boot graph（撞 v2 MetaData 直接炸 — FR-038 第一鐵則）。所有重寫只接 jedi_oscal_v2 / v2 repo / raw SQL。
3. canonical pattern（B1 已驗）：新/改 app service 包 v2 primitive → OscalContainer wire → route 改 import 接新 service → EXCLUDE_MODULES 移除 + api/oscal/__init__.py 註冊舊 URL → BOOT + smoke + pytest 不多紅 → 顯式 git add commit。
4. 動 v2 套件：dev path-dep（BE 重啟生效），不發 Nexus、不 commit pyproject，整 feature 完 + user 明示才發版。
5. 每階段獨立可 ship、可手測；FE 全程不需改。

端點（舊 URL，FE 既有）

FE response shape（adapter 要回的欄位）

uid, version, release_date, publish_status, framework_uid, framework_name, parent_version_uid, parent_version, catalog{概覽}, is_root, children[], created_user/_name, updated_user/_name, created_at, updated_at

註：v2 framework_versions 欄位 = uid/framework_id/parent_id/version/catalog_id/publish_status/published_at；release_date v2 schema 是否有需驗（沒有就回 null 或用 published_at）。

步驟

1. v2 套件 FrameworkService 補（dev path-dep）：
   • update_version(entity)、delete_version(uid)（repo 已有 update/delete_by_uid）
   • list_versions_by(query) 支援 parent_id / is_root（parent_id IS NULL）過濾（query entity 已有 framework_id + parent_id）
2. 新 app/oscal/service/framework_version_app_service.py（@transaction，包 v2 FrameworkService）：menu / list+pager（樹過濾 + framework_name enrich）/ get / create / update / delete；對齊舊 shape。
3. DI：oscal_containers.py 加 framework_version_app_service provider。
4. route：oscal_framework_version_route.py 改 import 新 app service（拔 v1 OscalFrameworkVersionService）。
5. re-enable：config/di_modules.py 移除 oscal_framework_version_route；api/oscal/__init__.py 註冊舊 URL。
6. BOOT + smoke（用既有 framework）+ pytest baseline diff + commit。

待驗

• v2 framework_versions 有無 release_date 欄位（FE 讀 release_date）；無 → adapter 補 null 或對應欄位。
• FE 版本列表是否硬依賴 catalog 概覽（控制數）；需要就 enrich。

端點（舊 URL）

步驟

1. v2 套件 CatalogService 補（dev path-dep）：get_catalog_tree_by_version 或重用既有 get_control_tree；update_group/update_control/update_part、delete_group/delete_control/delete_part（repo 已有 update/delete_by_uid + 級聯需自寫）。
2. 改寫 app/oscal/service/framework_version_edit_service.py：拔 v1 catalog domain service import，改接 v2 CatalogService / v2 catalog repos；保留雙軌守門（_require_draft + _has_profile_references 改查 v2 profile_imports）。
3. DI：provider 改 wire v2。
4. re-enable：移除 framework_version_edit_route（含 catalog_control_assessment 同檔）；註冊舊 URL（/oscal-catalog-group 等）。
5. BOOT + smoke（改/刪一個 draft catalog 的 group/control/AO）+ pytest + commit。

待驗

• has_references 判定：v2 profile 引用控制集的查法（profile_imports → 控制清單）。
• 跨 group 搬家 / 跨 control 重綁在 v2 model 的外鍵（control.catalog_group_id / part.catalog_control_id）。

端點（舊 URL）

parsed_result 結構（FE 既有）

{ groups:[{uid,name,description,parent_group_uid,order_no}], controls:[{uid,control_id,control_title,description,guidance,group_uid,order_no}], assessments:[{uid,name,description,control_uid,order_no}] }

關鍵風險 / 設計

• parse-job service 現用 v1 OscalImportService.parse_pdf_to_dict + import_from_dict → 不能進 boot graph。
• 需 v2「parse PDF → dict（不寫入）」能力：v2 CatalogService.import_catalog_from_pdf 是 parse+寫一次完成；兩階段需「只 parse 出 dict 供預覽」。
  • 方案 A：v2 補 parse_pdf_to_dict(stream, parser_code) -> dict（把 v1 parser 邏輯搬進 v2，與 import_catalog_from_pdf 共用底層 parser）。
  • 方案 B：confirm 時用 decisions/overrides 整理出最終 dict，再走 v2「from dict 寫入」（需 v2 有 add_catalog_from_dict 或用 add_catalog + entity 組裝）。
• oscal.framework_parse_jobs 表在主專案 infra（已存在）；parsed_result/import_summary 是 JSONB，與套件無關，可留。
• parse-job domain service / repo 在主專案，檢查是否 v1-clean（不 import jedi_oscal）。

步驟

1. 先釘死 v2 parse 能力（讀 import_catalog_from_pdf 內部 parser，抽出 parse-only）。
2. v2 套件補 parse_pdf_to_dict + 「from dict 寫入（含 decisions 後的最終 dict）」。
3. 重寫 framework_parse_job_service 接 v2（拔光 v1 import）。
4. DI wire + 移除 EXCLUDE + 註冊舊 URL（4 條）。
5. BOOT（先 import-probe 確認無 v1 NameError）+ real PDF smoke（CMMC L2）+ pytest + commit。

• 每階段：create_app() BOOT OK + python -m pytest test/ 不多於 baseline 紅（baseline-diff）+ 顯式 git add commit（BE 與套件分開）。
• FE 全程不需改；手測走既有三頁。
• push / 收尾（changelog/SUMMARY/memory/Notion）/ 套件發版 → 等 user 明示。
• pyproject.toml dev path-dep 勿 commit。

• profile route（oscal_profile_route）/ catalog_control_assessment 獨立 route — 視 FE 是否用到再評估。
• 資源庫 / 專案 / SSP / AP / AR 等其他 B 區塊。