# SSP OSCAL Alignment — Phase 3 / Phase 4 接手 Handoff — 2026-05-25

| 項目 | 內容 |
|---|---|
| 接手範圍 | Phase 3（Excel/Docx 樣板重設計）+ Phase 4（FE preview UI 重設計）|
| 起點 commit（主專案） | `d12bd705`（feature/ssp-oscal-alignment branch；30 commits ahead of origin，全 local 未 push）|
| 起點 commit（jedi-oscal）| Phase 1 ship 全 local（18 commits ahead）|
| Phase 1+2 收尾 SUMMARY | `docs/features/FR-028-2605-ssp-oscal-alignment/handoff/2026-05-25-phase1-phase2-FINAL-SUMMARY.md` |
| 建議切法 | **先 Phase 4 → 再 Phase 3 → 最後處理 Bug C / L1 套件進版** — 理由見 §3 |
| 預估天數 | Phase 3: 4d（design.md §3）+ Phase 4: 5d（design.md §4） — 兩 phase 可有重疊（Phase 4 不依賴 Phase 3 Excel 改完）|

---

## 0. 一句話結論（接手者最先看這段）

**user 在 template-edit 看不到 import 結果 = Phase 4 沒做**。Phase 1+2 已把 BE 寫對（DB 4 新表 + RLS + ConfirmService pipeline），但 FE template-edit 5-tab 還是舊架構（讀 jedi_device / jedi_information_system 舊概念表）→ user 看到「外部利用服務 (1)」「設備 (0)」「資訊系統 (0)」，**4 個 components 在 FE「不存在」**。要 demo readiness，先做 Phase 4。

---

## 1. 必讀文件清單（按順序）

| # | 文件 | 為何讀 | 重點段 |
|---|---|---|---|
| 1 | `docs/features/FR-028-2605-ssp-oscal-alignment/handoff/2026-05-25-phase1-phase2-FINAL-SUMMARY.md` | 知道 Phase 1+2 ship 了什麼 / 留了什麼 leftover | §7.4（Hotfix）/ §8（Leftover）/ §9（demo gap）|
| 2 | `docs/features/FR-028-2605-ssp-oscal-alignment/design.md` §3 + §4 | Phase 3 + Phase 4 scope | §3.1-§3.3 Excel/Docx 樣板；§4.1-§4.4 FE Tab 重設計 |
| 3 | `docs/features/FR-028-2605-ssp-oscal-alignment/design.md` §11.13 / §11.16 / §11.17 | Phase 2 留下的 reconciliation + 教訓 | 全 |
| 4 | `domain/oscal/import_pipeline/normalizer.py` | 理解 v2-bundle dict shape（Phase 3 Excel parser 要產出這個 shape）| 全 |
| 5 | `domain/oscal/adapter/cmmc_ssp_adapter.py` `adapt_to_bundle()` | Docx 端 v3 輸出 reference（Phase 3 Excel parser mirror 這個）| 該方法 |
| 6 | `app/oscal/service/ssp_excel_import_app_service.py` `_apply_content_overrides()` | Phase 4 開工前要 fix 的 Bug C — Excel 怎麼做的，docx 要 mirror | line 1242-1370 |
| 7 | `app/oscal/service/ssp_docx_import_app_service.py` `_run_v2_bundle_confirm()` | Bug C 要改的入口 | line 697+ |
| 8 | `domain/oscal/service/ssp_shell_service.py` | Bug A fix 抽出的新 service，Phase 4 可能會用到 | 全 |
| 9 | FE repo `~/Projects/Billows/Audit-Manager/compliance-manager-fe` `src/views/template-edit/`（Phase 4 才需要）| Phase 4 改 FE 時的對應路徑 | 找 5-tab 元件 |

**Conversation history**：`docs/conversation-history/2026-05-24/ssp-oscal-alignment-phase2/` + `.../ssp-oscal-alignment-phase2-closeout/`（後者是 Phase 2 收尾 + Bug A + RLS hotfix 的 raw dump）。

---

## 2. Phase 3 + Phase 4 範圍速覽

### 2.1 Phase 3 — Excel/Docx 樣板重設計（design.md §3）

| 子段 | 範圍 | 影響 |
|---|---|---|
| §3.1 Excel sheet 重組 | 04_設備 → 04_資產清冊；06_外部利用服務 → 06a_元件清冊 + 06b_利用授權；05_資訊系統刪除 | TEMPLATE_VERSION 0.x → 3.0.0（major bump）|
| §3.2 Docx 樣板加表 | H2 System Components / Hardware Maintenance / Leveraged External Systems 三段加表 + 加 anchor 進 `docx_section_extractors.py` | Docx 樣板 .docx 檔要實際編輯 |
| §3.3 Reference template 重產 | `scripts/regenerate_reference_templates.py` 跑 v3.0.0 | 測試 fixture 重產 |
| **§3.X Excel parser fix（從 §11.13 帶出來）** | `domain/oscal/parser/excel/cmmc_excel_parser.py` 輸出 `parsed_result["schema_version"] = "v2-bundle"` + components / leveraged_authorizations / inventory_items 三 list（mirror Docx Task 8 `adapt_to_bundle`）| Excel import 從 412 → 200 + 寫入新表 |

**Phase 3 唯一阻擋條件**：Excel parser fix 必須在 §3.1 sheet 改完後做（parser 要對應新 sheet 名）。

### 2.2 Phase 4 — FE preview UI 重設計（design.md §4）

| 子段 | 範圍 |
|---|---|
| §4.1 Tab 結構 | 舊 5 tab → 新 5 tab：`[基本資料][受評標的][參與人員][元件 + 授權 + 資產][控制項]`；第四 tab 全新 |
| §4.2 第四 tab 內部結構 | 3 sub-panel：元件清冊 DataTable / 利用授權 Card list / 資產清冊 DataTable；leveraged_auth ref 用 VLOOKUP-style chip |
| §4.3 元件 component 主 component 重設計 | 新 `SspComponentsLeveragedInventoryTab.vue` 取代 `LeveragedSection.vue`（廢棄）|
| §4.4 Reuse excel preview component | Excel side 既有 `SheetPreviewLeveraged.vue` 等 generalize 後 docx-import-v2 共用 |

**Phase 4 唯一阻擋條件**：BE 端 read API 必須能回新表內容。Phase 2 已 ship `ssp_components` / `ssp_leveraged_authorizations` / `ssp_inventory_items` 寫入；read endpoint 需要 audit 一遍。

---

## 3. 建議切法 — 先 Phase 4 → 再 Phase 3

### 3.1 為何先 Phase 4？

| 理由 | 說明 |
|---|---|
| Demo readiness | user 看不到 import 結果是當前最大痛點（§9 demo gap）；Phase 4 才解 |
| Docx 已能 import | Phase 2 ship 後 docx import 全通；Phase 4 不被 Phase 3 卡 |
| Phase 3 主要影響 Excel | Excel import 從 412 → 200 重要但不阻擋 docx 端 demo |
| FE 改動 BE 配合度低 | Phase 4 主要 FE work（template-edit 重寫），BE 端只需 audit read endpoints；可平行做 |

### 3.2 為何不先 Phase 3？

- Phase 3 Excel sheet 重組要動既有 reference templates + 測試 fixtures，影響面大；做完仍解不了 demo gap。
- Phase 3 §3.X Excel parser fix 確實重要，但 user 端可暫時「Excel 帶不進新表，請用 docx」workaround；Phase 4 之後再做。

### 3.3 開工順序建議（user 拍板「衝一下 3, 4」的最佳路徑）

```
Step 1 → Phase 4 開工前必做：fix Bug C（v2-bundle confirm 套 content_overrides，見 §4.2）
Step 2 → Phase 4.1 + 4.2 + 4.3 FE template-edit 重設計（5d）
         同時 BE 端 audit read endpoints 對 4 張新表（半天，並行）
Step 3 → 確認 user 在 template-edit 能看到 docx import 結果 → demo readiness 解鎖
Step 4 → Phase 3.X Excel parser fix（恢復 Excel import 200）
Step 5 → Phase 3.1-3.3 Excel/Docx 樣板重設計（含 TEMPLATE_VERSION bump）
Step 6 → 全 ship 完，user 拍板 → L1 jedi-oscal 0.0.18 → 0.1.0 bump + push（§5）
```

---

## 4. 開工前必處理（Phase 4 第一個 commit 前）

### 4.1 Bug B — docx import 5 parties 全 skip → 0 parties 寫入

| 項目 | 內容 |
|---|---|
| 推測 | FE diff stepper 預設 `decision=skip`；user 沒手動切換就 confirm → BE 全 skip 是正確行為 |
| Phase 4 必做 | (a) FE 重設計時把 party diff 預設改 `accept` 或加 highlight；(b) BE 端 audit response 顯示的 decision distribution；(c) 釐清 user 在 UI 上看到的 vs BE 收到的 payload 是否一致 |
| 不能直接「accept by default」| 風險：user 沒看 diff 就誤寫資料；要 UX 一起設計（pre-select all + visible counter）|

### 4.2 Bug C — v2-bundle confirm 路徑沒套 `content_overrides`

**這個必須先 fix，不然 Phase 4 FE 改 preview UI 後 user 編輯不會生效，整個 Phase 4 demo 失敗**。

| 項目 | 內容 |
|---|---|
| 症狀 | user 在 docx preview UI 改 component 類型 / LA 欄位 → submit 後 DB 仍是 parse 時原值 |
| Root cause | `ssp_docx_import_app_service._run_v2_bundle_confirm` 入口直接 `dict_to_bundle(parsed_result["bundle"])`；**沒套 `content_overrides`**。對比 Excel side `ssp_excel_import_app_service._apply_content_overrides` 有完整 metadata / system_characteristic / sheet rows / controls overrides handling |
| Fix outline | 在 `_run_v2_bundle_confirm` 入口加 `_apply_content_overrides_to_bundle()` helper：拆 overrides 對 bundle.components / bundle.leveraged_authorizations / bundle.inventory_items 三 list 做 row-level update（mirror Excel `_apply_content_overrides` 的 sheet-row loop logic）|
| 設計決策 | Excel side override 是針對 parsed_result dict path（`row_overrides[sheet_key][row_idx]`）；v2-bundle 已是 dataclass list → 要先決定 mapping 策略：(a) idx-based mapping（FE 送 `{"components": {0: {...}, 1: {...}}}`）；(b) uid-based mapping（用 ParsedComponent.uid_ref；目前 v2-bundle 的 uid_ref 是 parse-time 生成，前後一致）。建議 (b) — 安全（idx-based 對 normalize 後重排不抗壓）|
| Test | `tests/test_ssp_docx_import_app_service.py` 加 case：preview 改 component type + LA title → confirm 後 DB 看到 override 後的值 |

### 4.3 Pre-flight checklist

```bash
# 1. 兩 repo branch:
git branch --show-current  # 預期 feature/ssp-oscal-alignment
git -C ~/Projects/Jedicogy/module/jedi-python-package/jedi-oscal branch --show-current

# 2. Dev DB Phase 2 final state（密碼請查 .env）：
psql -h 192.168.50.188 -p 25432 -U cmmgr -d guidant_ai_dev -c "
SET app.is_super_admin='t';
SELECT
  (SELECT count(*) FROM oscal.ssp_leveraged_authorizations) AS la,
  (SELECT count(*) FROM oscal.ssp_components) AS comp,
  (SELECT count(*) FROM oscal.ssp_inventory_items) AS inv;"
# 預期: la=12, comp=341, inv=0

# 3. Smoke baseline:
tail -50 log/app.log              # 預期無 Traceback
pytest tests/test_ssp_docx_import_app_service.py  # 應綠（32 既有 + Phase 2 新加）

# 4. 驗 demo gap 是否還在（Phase 4 完成的 acceptance）:
#    MF 62c31d47-a90e-40e0-98ae-cb0c164a8acc / SSP id=260
psql -h 192.168.50.188 -p 25432 -U cmmgr -d guidant_ai_dev -c "
SET app.is_super_admin='t';
SELECT id, uid, title FROM oscal.ssp_leveraged_authorizations WHERE ssp_id=260;
SELECT id, uid, title, component_type FROM oscal.ssp_components WHERE ssp_id=260;"
# 預期: 1 LA + 4 components — FE 改完 Phase 4 後 template-edit 第四 tab 必須全 4 個都看得到
```

---

## 5. 結尾必做（Phase 3+4 全 ship 後）

### 5.1 L1 — jedi-oscal 0.0.18 → 0.1.0 bump + Nexus push + 主專案 pin 還原

User 拍板才執行（見 §7.1 of `2026-05-25-phase1-phase2-FINAL-SUMMARY.md`）。建議 Phase 3+4 ship 完一次處理 — 中間還會改 jedi-oscal（Phase 5 export 端）就再 bump 一次成本高。

### 5.2 兩 repo `git push`

兩 repo 都還 local（主專案 30 commits ahead；jedi-oscal 18 commits ahead）。Push 需 user 明確指示（per CLAUDE.md「push 永遠要 user 明確指示」）。

### 5.3 Phase 3+4 收尾文件

收尾時參照 Phase 1+2 SUMMARY 模板產出：

- `docs/features/FR-028-2605-ssp-oscal-alignment/handoff/<YYYY-MM-DD>-phase3-phase4-FINAL-SUMMARY.md`
- `docs/changelog/<YYYY-MM-DD>-feat-ssp-oscal-alignment-phase3-phase4.md`
- design.md §11 補新增的 reconciliation entries
- 對話紀錄 extract 到 `docs/conversation-history/<YYYY-MM-DD>/ssp-oscal-alignment-phase3-4-{...}/`

---

## 6. 精簡開工 prompt（直接複製貼）

```
你接手 SSP OSCAL Alignment Phase 3 + Phase 4。Phase 1+2 完整 SHIPPED（30 主專案 + 18 jedi-oscal commits，全 local 未 push）。

按以下順序讀文件：
1. docs/features/FR-028-2605-ssp-oscal-alignment/handoff/2026-05-25-phase1-phase2-FINAL-SUMMARY.md §7.4 / §8 / §9（必看 user-facing demo gap）
2. docs/features/FR-028-2605-ssp-oscal-alignment/handoff/2026-05-25-phase3-4-handoff.md（本文件 — 完整 Phase 3+4 範圍 + 建議切法 + Bug B/C）
3. docs/features/FR-028-2605-ssp-oscal-alignment/design.md §3（Phase 3）+ §4（Phase 4）+ §11.13 §11.16 §11.17
4. domain/oscal/import_pipeline/normalizer.py（v2-bundle dict shape）
5. domain/oscal/adapter/cmmc_ssp_adapter.py adapt_to_bundle()（Docx v3 輸出 reference）

開工前 pre-flight 跟 acceptance verify SQL 見 handoff §4.3。

建議切法：先 Phase 4（解 user-facing demo gap）→ 再 Phase 3（Excel parser fix + 樣板重設計）。

開工第一個 commit 前必做：
- Bug C fix（_run_v2_bundle_confirm 套 content_overrides）— Phase 4 demo 阻擋條件
- Bug B 釐清（5 parties 全 skip）— BE/FE 共查

收尾後（user 拍板）：L1 — jedi-oscal 0.0.18 → 0.1.0 bump + Nexus push + 主專案 pin 還原 + 兩 repo git push。
```

---

## 附錄 A — 路徑速查

| 用途 | 路徑 |
|---|---|
| Phase 1+2 FINAL SUMMARY | `docs/features/FR-028-2605-ssp-oscal-alignment/handoff/2026-05-25-phase1-phase2-FINAL-SUMMARY.md` |
| 本 handoff | `docs/features/FR-028-2605-ssp-oscal-alignment/handoff/2026-05-25-phase3-4-handoff.md` |
| Spec v1.2 + §11 reconciliation 17 條 | `docs/features/FR-028-2605-ssp-oscal-alignment/design.md` |
| Phase 1 plan | `docs/features/FR-028-2605-ssp-oscal-alignment/implementation-plan-phase1.md` |
| Phase 2 plan | `docs/features/FR-028-2605-ssp-oscal-alignment/implementation-plan-phase2.md` |
| Import pipeline 共用 module | `domain/oscal/import_pipeline/` |
| Docx adapter | `domain/oscal/adapter/cmmc_ssp_adapter.py` |
| Docx app service | `app/oscal/service/ssp_docx_import_app_service.py` |
| Excel app service | `app/oscal/service/ssp_excel_import_app_service.py` |
| SspShellService（Bug A fix 抽出）| `domain/oscal/service/ssp_shell_service.py` |
| Conversation history | `docs/conversation-history/2026-05-24/ssp-oscal-alignment-phase2{,-closeout}/` |
| FE template-edit（Phase 4 主戰場）| `~/Projects/Billows/Audit-Manager/compliance-manager-fe/src/views/template-edit/` |