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

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。

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.1 Phase 3 — Excel/Docx 樣板重設計（design.md §3）

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

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

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

3.1 為何先 Phase 4？

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.1 Bug B — docx import 5 parties 全 skip → 0 parties 寫入

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

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

4.3 Pre-flight checklist

# 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.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-{...}/

你接手 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。