# 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 遷移）**。

---

## §0 TL;DR

- **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）。

---

## §1 已完成成果座標

### Wave 0 契約（主專案，commit `dad80aef` + `471862d8`，已 commit 未 push）
- [requirement-analysis.md](../requirement-analysis.md) — 需求 + 10 決策（D1-D7 + Q1-Q4）
- [design.md](../design.md) — 契約層 + engagement 模型 + 套件介面 + API skeleton
- [oscal-v2-deltas.sql](../oscal-v2-deltas.sql) — base(42) 上的 6 delta
- [implementation-plan.md](../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 Wave 2（BE 遷移）冷接資料 —— 這是你要做的

### §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…），非全平行

---

## §3 全域 follow-up / 已知問題
- 套件待發 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；正式不能這樣）

## §4 規範文件齊全度
- ✅ 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）