FR-038 Wave 2 — 主專案 BE 遷移 Implementation Plan

For agentic workers: 用 superpowers:subagent-driven-development 逐 task 執行。Steps 用 - [ ]。 上游：Wave 1（jedi-oscal-v2 套件）已完成，見 handoff。契約：design.md + oscal-v2-deltas.sql + api-contract.md。

Goal: 把主專案 compliance-manager-be 從舊 jedi-oscal 0.0.22 遷移到 jedi-oscal-v2，落地新業務流程（專案成立 clone 三件組、稽核輪次 project_audit_rounds、AP 延後到輪次、AR AO 全量矩陣、整改三層），讓 dev BE 從「新 schema + 舊 code 壞掉」恢復成可運作的新架構。

Architecture: ~110 檔（live grep 2026-06-14 = 109 source 檔，含 test 約 115）分 Type A（改 import+呼叫）/ B（改簽名+業邏輯）/ C（整段重寫）。DI 容器一次切換到 v2、同批改所有 consumer。新增 project_audit_rounds 為輪次 first-class。重建 DROP CASCADE 掉的 FK/view。

Tech Stack: Flask + SQLAlchemy 2.0 + PostgreSQL（DDD），jedi-oscal-v2（path-dep dev），pytest（test/）。

Scope: 只 BE（主專案）。FE 是 Wave 3。估 62–81h。

• 讀 handoff §2（遷移盤點 + DROP CASCADE 待重建 + Type C 重寫點）
• 讀 jedi-oscal-v2 對外 service 簽章（handoff §1 列表）+ 套件 __init__.py
• 確認主專案 pyproject.toml 已有 jedi-oscal-v2 path-dep（dev-only，未 commit）
• 驗 dev BE 起得來：遷移過程中常態壞，每個 phase 末跑 python main_socketio.py smoke + 既有 pytest test/ baseline diff（記憶 feedback_baseline_worktree_regression_diff）

Phase 2.0 前置（序列瓶頸）
  ├─ 2.0a DI 容器切換 v2 + Type A 批次改 import（一起做，否則 DI 一切就全壞）
  ├─ 2.0b 重建 / 廢棄 compliance FK（fk_ape）
  └─ 2.0c 重寫 vw_user_job_queue（對新 ap_tasks）
       ▼
B1 框架 + 資源庫 API 對齊新套件 ── 相對獨立，可與 B2 並進
       ▼
B2 專案成立流程重寫（clone 三件組，AP/AR 延後）   ← Type C
       ▼
B3 SSP 維護 + 啟動稽核 snapshot + project_audit_rounds 狀態機   ← Type C
       ▼
B4 AP 後端（草稿生成 + CRUD + subjects）
       ▼
B5 AR（AO 全量矩陣 + 風險總結）+ POA&M（整改三層 + 結案/覆核）   ← Type C
       ▼
Phase 2.Z 全 e2e（精誠機械 CMMC 劇本）+ baseline 零回歸

能平行的：Type A 批次（純改 import）可多 agent 分檔平行；B1 與 B2 可並進。必序列的：2.0a（DI 一切）、B2→B3→B5 的業務鏈、Type C 重寫。

Task 2.0a: DI 切換 v2 + Type A 批次改 import

⚠️ 本段「~40 檔 import-rename」框架已被 2026-06-14 驗證推翻 —— v2 是結構性重寫（domain-service 層收掉、AO/AP-task/AR-data 表結構全變），且新舊套件 ORM model 撞同一 MetaData 無法共存（全切被強制、無 booting 中間態）。2A 正解是 gut-and-disable（v2 primitives 接真、B1~B5 業務面乾淨 disable、My Jobs 重寫），不是 import-rename，也不是 stub-everything。完整修正版執行計畫見 handoff/2026-06-14-2A-corrected-gut-and-disable-handoff.md（含 boot 必經面清單 / v2 wiring map / disable 手法 / My Jobs 重寫 / boot 驗證指令）。

Files: di_containers/oscal/oscal_containers.py（實際 1074 行，verified —— 是 Phase 2.0 最大單一工作量，別照舊估的 150 行排程）+ ~40 Type A 檔（infra model/mapper/repo、domain entity import）

• 重寫 OscalContainer：31+ provider 從 jedi_oscal.* 改 jedi_oscal_v2.*（service/repo），對照新套件對外 service 清單。
• 批次改 Type A 檔的 import（from jedi_oscal → from jedi_oscal_v2），調整改名/搬移的 symbol。顯式 git add 分批 commit，禁 -am（記憶 feedback_subagent_explicit_git_add）。
• 注意：舊套件有些 model 在新套件改名/結構變（如舊 assessment_result_datas 沒了、AO 從 catalog_control_assessments 改 catalog_control_parts）→ 這些 consumer 落 Type B/C，本 task 只搬「直接對應」的。
• 驗：python -c import smoke 全綠 + DI container wire 不炸。
• commit。

Task 2.0b: compliance FK 重建 / 廢棄判定 ⛔ USER-DECISION GATE，不要自己決定

Files: 新 migration scripts/sql/2026-XX-XX-fr038-wave2-rebuild-fk.sql

• 這是架構決策（keep+rebuild vs DROP），停下問 user，不要 agent 自己拍：compliance.assessment_plan_extensions 在新 project_audit_rounds 模型下是否還需要？
  • 我的建議（給 user 參考）：新架構輪次/AP 關聯已搬到 project_audit_rounds，assessment_plan_extensions（module_frame_id/owner_id 等 AP 延伸）很可能被 project_audit_rounds + project_extensions 取代 → 傾向 DROP；但需 grep 確認其 live consumer（grep -rl assessment_plan_extension app/ infra/ domain/）零引用才能 DROP。
• user 拍板後才動：保留 → 查 orphan（assessment_plan_id NOT IN (SELECT id FROM oscal.assessment_plans)）清理 → ALTER TABLE ... ADD CONSTRAINT fk_ape_assessment_plan ...；廢棄 → 記錄決策 + DROP。
• migration 走 cmmgr + --single-transaction -v ON_ERROR_STOP=1 + INSERT schema_migrations（記憶 SQL 鐵則）。

Task 2.0c: 重寫 vw_user_job_queue

Files: scripts/sql/view/vw_user_job_queue.sql（重寫）+ infra/participant/model/vw_user_job_queue.py（ORM mirror 跟著改）+ consumer infra/participant/repository/task_assignee_repo_impl.py

• 不能 replay：原 view join 的 4 張舊 AP 表（assessment_plan_task_workflow_execution_mapping / assessment_plan_controls / assessment_plan_groups / assessment_plan_tasks）新 schema 都沒了。
• 對齊 Q1：任務執行 job 綁「專案 SSP 控制項」、非 AP task。重寫 view 對新來源（SSP 控制項 + workflow_execution + task_assignees + job_executions）。
• ORM mirror + repo consumer 跟著新 column set 改。驗 My Jobs 頁資料正確。

Files: api/module_frame/、app/module_frame/service/*、相關 repo

• 框架 CRUD/匯入：改呼叫 jedi_oscal_v2 FrameworkService / CatalogService（CMMC parser）。
• 資源庫（module_frame）：改成 catalog+profile+ssp 三件組語意；建立資源庫時 resolve_profile → catalog 副本（邊界①）。匯入 SSP docx/excel 落地新 schema（注意：套件 docx/excel 匯入 是 follow-up，本期若需要要先補套件或暫沿用舊路徑轉接）。
• 對齊 api-contract.md 框架/資源庫段。

Files: app/project/service/oscal_project_service.py（核心重寫）+ api/project/routes/project_route.py

• start_oscal_project() 拆成 start_project：clone 最新發布資源庫三件組（clone_resource_library 邊界②）+ 建 project 主檔 + participant + 為 SSP 控制項建 workflow job（Q1，專案成立就建，非 AP task）。AP/AR 不在此建。
• 移除舊「啟動時建 AP/AR + 為 AP task 建 workflow」邏輯。
• 改 project_assessment_plan_mapping 等關聯（AP→ project_audit_rounds）。
• 對齊 api-contract project-start 段。全 e2e（建專案→看到三件組 clone）。

Files: app/oscal/service/*（SSP）、新 app/grc/service/audit_round_service.py、api/grc/routes/

• SSP 維護路由對齊新 jedi_oscal_v2 SspService（system-characteristics/parties/components/inventory/implemented-requirements/SoA props）。
• 新 project_audit_rounds 狀態機（7 態，見 oscal-v2-deltas.sql）：建輪次 / launch-audit（snapshot living SSP → snapshot_ssp 邊界③ → 填 round.ssp_id + 建/沿用 engagement 的 AP+AR）/ launch-reverify（close-out 開新 round，parent_round_id）。狀態轉換驗前置條件 + 角色權限（manager/auditor）+ error code（GRC_ROUND_*）。
• 對齊 api-contract audit-rounds 段。

Files: app/grc/service/*、api/grc/routes/assessment_plan_route.py

• AP 草稿生成（generate_draft from SSP 快照）+ reviewed-controls / subjects(抽查名單) / tasks CRUD，wire 到 jedi_oscal_v2 AssessmentPlanService。
• 權限：auditor 寫 AP。對齊 api-contract AP 段。

Files: app/grc/service/audit_service.py、infra/grc/repository/grc_audit_repo_impl.py（重寫）、app/grc/service/poam_service.py、api/grc/routes/{audit_route,poam_route}.py

• AR 判定從「逐控制項 verdict」改 AO 全量矩陣（init_finding_matrix / upsert_finding / list_findings w/ stats），重寫 grc_audit_repo_impl 的 8+ 查詢。
• 風險總結（新畫面後端）：稽核員手動建 risk + link_findings 多對多 + 等級在 risk 層（AssessmentRiskService）。
• POA&M：generate_from_findings（gate 在 AR 定版後，避免重複生）+ 整改三層（remediation→milestone，per-milestone assignee）+ 結案（全 POA&M closed）+ 覆核（launch-reverify）。
• error code（GRC_AR_* / GRC_RISK_* / GRC_ROUND_*）。對齊 api-contract AR/POA&M 段。

• 全 e2e 走一次完整生命週期（精誠機械 CMMC L2：建專案→編 SSP→啟動稽核 snapshot→AP→AR AO 判定→風險→POA&M→覆核→結案）。
• baseline 零回歸：跟遷移前 commit 的 pytest test/ diff（記憶 feedback_baseline_worktree_regression_diff）。
• BE 起得來 + 主要 route smoke。
• （收尾：等 user 明示才 changelog/SUMMARY/發版套件）。

• DI 一切性：2.0a 沒一次切乾淨會讓整個 BE import 炸 —— Type A 批次要跟 DI 同 PR 完成才能起 BE。
• 舊表沒了：consumer 引用舊 assessment_result_datas / catalog_control_assessments / 舊 AP 子表的，要改對新結構（Type B/C），不是改 import 就好。
• 跨 schema FK 字串帶 schema 前綴（記憶 feedback_cross_schema_fk_must_qualify）。
• 套件 docx/excel 匯入是 follow-up：B1 若需要 SSP 匯入，要嘛先補套件、要嘛暫接舊路徑——開工前確認。
• 正式環境（D7）：dev 用 drop&rebuild，stg/poc/prod 遷移策略未定，上正式前必須有可移植 migration（不能 drop schema）。
• 每個 Type C 完成各自全 e2e，不要堆到最後。