FR-038 — Wave 1 SUMMARY + Wave 2 Handoff（自包含，可冷接）

日期：2026-06-14 · branch（三 repo 皆）：feature/oscal-refactor · 皆未 push 給下個 session：Wave 0（契約）+ Wave 1（jedi-oscal-v2 套件）已完成。本文件讓你冷接 Wave 2（主專案 BE 遷移）。

• Wave 0 契約 ✅ 完成（schema delta + design + plan，皆過審查）。
• Wave 1 套件 jedi-oscal-v2 ✅ 完成：42 表 + 全核心邏輯 + snapshot/clone + CMMC 匯入 + OSCAL JSON 匯出，194 tests 全綠，最終 review Approved。
• ⚠️ 現狀：dev DB 的 oscal schema 已 drop & 重建成新結構；但主專案 BE 仍跑舊 jedi-oscal 0.0.22 → dev 的 OSCAL 功能目前是壞的，要 Wave 2 把 BE 遷到新套件才恢復。
• Wave 2 = 大遷移：115 檔 import 舊套件，估 62-81h。需先寫 Wave 2 implementation-plan + 補完整 API 契約，再執行（建議獨立 session）。

Wave 0 契約（主專案，commit dad80aef + 471862d8，已 commit 未 push）

• requirement-analysis.md — 需求 + 10 決策（D1-D7 + Q1-Q4）
• design.md — 契約層 + engagement 模型 + 套件介面 + API skeleton
• oscal-v2-deltas.sql — base(42) 上的 6 delta
• implementation-plan.md — Wave 1 計畫

Wave 1 套件（~/Projects/Jedicogy/module/jedi-python-package/jedi-oscal-v2/，57 commits，未 push、未發 Nexus）

• 42 model + 23 app/domain service + 194 tests（DEV DB round-trip）
• import 名 jedi_oscal_v2；base class 來自 jedi-common（BaseRepositoryImpl[Entity,Query,Model,Mapper]、Base/BaseModel、transaction）
• 對外 service（主專案 Wave 2 import 點）：FrameworkService / CatalogService / ProfileService（+resolve_profile）/ SspService(+deep_clone_ssp) / AssessmentPlanService(+generate_draft) / AssessmentResultService / AssessmentRiskService / PoamService(+generate_from_findings) / RemediationService / OscalSnapshotService(snapshot_ssp/clone_resource_library) / OscalIoService(export_oscal) / ports.oscal_parser_factory.get_oscal_parser_adapter
• 重要 pattern 決策（沿用）：id-only 表 entity 帶 uid: Optional[str]=None sentinel（BaseRepositoryImpl.update 讀 entity.uid）；uuid-identity 用 mapped_column("uuid", PG_UUID, key="uid")；FK-to-built→真 FK + 模組頂 import target，FK-to-unbuilt→plain BigInteger；app service 不加 @transaction（caller 開 scope）；測試用 tests/conftest.py rollback-isolated db_session（set app.is_super_admin='t' 繞 RLS）

dev DB 狀態

• oscal schema = 新結構（48 表：base 42 + delta 6），compliance.project_audit_rounds 在、3 條 FK 在、CHECK 在
• public.schema_migrations 已記 2 筆（base + delta）

§2.1 規模（discovery 盤點結果）

• 115 檔 import 舊 jedi_oscal（api 6 / app 50 / infra 30 / domain 25 / DI 4）
• 分類：Type A（改 import+呼叫，~40 檔）/ Type B（改簽名+業邏輯，~30 檔）/ Type C（整段重寫，4-6 檔）
• 估 62-81h

§2.2 Type C 核心重寫點（最高風險）

1. app/project/service/oscal_project_service.py — start_oscal_project() 拆成 start_project（clone 資源庫三件組，AP/AR 不在此建）+ launch_new_round（建 round → snapshot SSP → 建/沿用 AP+AR per engagement）
2. di_containers/oscal/oscal_containers.py — 150+ 行，31+ 套件 service/repo 重新註冊（舊 → jedi_oscal_v2）
3. infra/grc/repository/grc_audit_repo_impl.py — AR 從單行 verdict 改 AO 全量矩陣 查詢（8+ 個 OscalAssessment* query 全改）
4. 關鍵 FK 改向：project_assessment_plan_mapping（AP→ project_audit_rounds）、assessment_plan_task_workflow_mapping（task→ ？需對齊新 ap_tasks）、ssp_reference_documents.context_id

§2.3 DROP CASCADE 待重建（已查證）

• compliance.assessment_plan_extensions 的 FK fk_ape_assessment_plan → 被刪。可一行 ALTER 重建（target oscal.assessment_plans 還在）但先確認此表在 project_audit_rounds 模型下是否還需要（可能被取代）；重建前先查 orphan。
• public.vw_user_job_queue（My Jobs 資料源，scripts/sql/view/vw_user_job_queue.sql）→ 被刪，不能 replay：它 join 的 4 張舊 AP 表（assessment_plan_task_workflow_execution_mapping / assessment_plan_controls / assessment_plan_groups / assessment_plan_tasks）在新 schema 都沒了。要對新 oscal.ap_tasks + public.workflow_execution_control_mapping 重寫。ORM mirror infra/participant/model/vw_user_job_queue.py + consumer infra/participant/repository/task_assignee_repo_impl.py 要跟著新 column set 改。

§2.4 Q1 任務執行綁定（記得）

job 綁「專案 SSP 控制項」、專案成立就建、與輪次無關（不是綁 AP task）。舊 project-start 為 AP task 建 workflow 的邏輯要改成為 SSP 控制項建。

§2.5 建議 Wave 2 執行順序

1. 前置（序列）：DI 容器遷移（但因 115 檔還 import 舊套件，DI 不能孤立切換 —— 要跟 Type A 批次一起）+ 重建 fk_ape（若保留）+ 重寫 vw_user_job_queue
2. 補完整 API 契約（design §5 目前只有路由骨架）→ 解鎖 FE 平行
3. Type A 批次（可平行）→ Type B → Type C（序列重寫，每個全 e2e 測）
4. FE（Wave 3）用「垂直功能管線」跟在對應 BE 端點後（B4→C1、B5→C2…），非全平行

• 套件待發 Nexus（feature 全完成 + user 明示才 bump+推；屆時主專案 pin 版本 + 還原 pyproject path-dep 一起 commit）
• 主專案 pyproject.toml 的 jedi-oscal-v2 path-dep 是 dev-only，未 commit（刻意）
• generate_from_findings 無 idempotency guard → Wave 2 caller gate 在 AR 定版後
• deep_clone_ssp 子表 audit-user 沿用 source（cosmetic，Wave 2 可加 curr_user param）
• OscalIoService POA&M export query dispatch 靠 repo class 名 substring（fragile，Wave 2 可改傳 query class）
• D5 ISO 整合（risk_accepted deviation / L1⊂L2 / SoA 自選排除）全部 follow-up
• D7 正式環境（stg/poc/prod）schema 遷移策略未定（dev 用 drop&rebuild；正式不能這樣）

• ✅ changelog：docs/changelog/2026-06-14-feat-fr038-wave1-jedi-oscal-v2-package.md
• ✅ 本 SUMMARY/handoff
• ⏳ conversation-history 歸檔（本 session JSONL extract）— 收尾流程進行中
• ⏳ memory feedback（本 arc 教訓）— 收尾流程進行中
• ⏳ Notion 任務 — 收尾流程進行中
• ⏳ Wave 2 implementation-plan + 完整 API 契約 — 下一步（step 2）