SSP OSCAL Alignment — Phase 1 + Phase 2 FINAL SUMMARY — 2026-05-25

✅ Phase 1（Foundation） — OLD 單一 SspSystemImplementationItemEntity 拆成 OSCAL-correct 3 entity（LeveragedAuthorization / Component / InventoryItem + M2M join），落地到 DB + jedi-oscal 套件 + 主專案 BE 全層。12 LA + 341 components migrate verified。18 主專案 callers refactor 完成，舊表 + 舊 M2M 全 DROP。

✅ Phase 2（Import Pipeline 對接） — Import pipeline 拆出獨立 module domain/oscal/import_pipeline/（warnings collector / normalizer / bundle_restore / confirm_service 四檔）；3 個 v3 write strategy（LeveragedWriteStrategy / ComponentWriteStrategy / InventoryItemWriteStrategy）落地；orchestrator 採 Minimal scope（只保留 leveraged reconcile）；Docx adapter 加 adapt_to_bundle() 輸出 v3；Docx app service 走新 pipeline 全通；Task 11 cleanup 刪 5 src + 4 test 共 1057 LOC dead code。

⚠️ Excel parser gap（§6.2 / design.md §11.13） — Excel app service dispatch 落地但 parser 還沒輸出 v2-bundle dict shape，目前 Excel import 走 legacy path → 412。Phase 3 §3.X 接手。

✅ Subagent-driven mode 跑通（13 個 Phase 2 task），review-after-implementer pattern 多次截到 spec drift（如 Task 11B reviewer 加 SourceTable enum）。

Phase 1（14 tasks）

Phase 2（13 tasks）

Note：Plan 寫 Task 10 是 E2E pre-flight smoke，Phase 2 期間 user 拍板「重設計後寫」延到 Phase 3+ 一起做。Plan 也沒列 Task 11B（reviewer follow-up），實際是 Phase 2 review checkpoint 後自然產出的 minor cleanup。

jedi-oscal（18 commits，baseline 6f04da7；Phase 1 期間 ship，Phase 2 全 0 commit）

主專案（28 commits，baseline d6fab20）

Phase 1（14 commits）

Phase 2（14 commits）

oscal.ssp_leveraged_authorizations           rowsecurity=t   12 rows
oscal.ssp_components                          rowsecurity=t  341 rows  (164 hw + 165 system + 12 service)
oscal.ssp_inventory_items                     rowsecurity=t    0 rows  (Phase 3 Excel parser fix 後 Phase 2 confirm 流程才會寫入)
oscal.ssp_inventory_implemented_components    rowsecurity=t    0 rows  (M2M join)

舊表狀態（Phase 1 Task 12 DROP）：

• oscal.ssp_system_implementation_items → DROPPED
• oscal.ssp_inventory_item_components (OLD M2M) → DROPPED

FK linkage：12/12 service components 全綁回 leveraged_authorizations.uid（Phase 1 migration 期）。

Note：Phase 2 完工但 ssp_inventory_items 仍 0 rows 是因 Phase 2 期間沒新 import；新 import 經 Docx flow 應能寫入，Excel flow 待 Phase 3 §3.X parser 對齊。

4.1 Docx import — 完整 v3 path 通

POST /api/1.0/ssp-docx-imports/parse + POST /api/1.0/ssp-docx-imports/<uid>/confirm：

• Parse phase 同時 emit ParsedSsp overlay（Stage 1 docx-import-parity caller 仍依賴）+ v2-bundle ParsedExcelEntityBundle（merged into parsed_result with schema_version="v2-bundle"）。
• Confirm phase：controls / parties write 維持既有 path；LA → Component → InventoryItem 走新 SspImportConfirmService.confirm()（bundle_restore → normalize → orchestrator → 3 write strategies）。
• Bundle 失敗非 fatal — log warning + 422 fallback 不會 silent drop LA/Component data。

4.2 Excel import — 走 legacy path 拋 412（⚠️ Phase 3 §3.X 才能 close）

POST /api/1.0/ssp-excel-imports/.../confirm：

• App service dispatch logic 已落地（Task 7），但 parser 還沒輸出 schema_version="v2-bundle"。
• 結果：parsed_result.get("schema_version", "v1-ssp") == "v1-ssp" → 直接 raise PreconditionFailedError(GRC_DOCX_PARSE_JOB_LEGACY_SHAPE, 412)。
• 對使用者：Excel import flow 從「200 + 寫入舊表」變「412 提示重傳」。
• Phase 3 §3.X 改 Excel parser 後恢復 200 + 寫入新 OSCAL-correct 表。

4.3 移除的 dead code

Phase 2 Task 11A 刪：

• 5 個 src 檔（device_write_strategy.py / information_system_write_strategy.py / base.py AbstractSspComponentWriteStrategy / device_reconciler.py / information_system_reconciler.py）
• 4 個 test 檔（test_a4_write_all_data_pipeline.py / test_a4_reconciliation_device.py / test_a4_reconciliation_information_system.py / test_a4_boundary_cases.py）
• 3 個 v2 dataclass（ParsedDevice / ParsedInformationSystem / ParsedLeveraged）

未來 caller 若 import 上述 symbol 會 ImportError — Phase 3+ 引用者請 migrate 到 v3 dataclass + ConfirmService。

⚠️ 3 個 Phase 2 收尾留下的 leftover 抽到 §8（L1 / L2 / L3）獨立列，下方是更早期的 follow-up 清單。

6.1 Production / API（Phase 3+ 處理）

1. Excel parser v1→v2 gap（⭐ 最高優先 — Phase 3 §3.X）：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 + 寫入新表。
2. _parsed_ssp_to_dict_overlay 仍存在於 Docx app service（Stage 1 docx-import-parity 留下的 ParsedSsp overlay logic）— Phase 4 FE preview UI 重設計後可考慮整段刪掉，直接吃 v2-bundle。
3. 7 個 pre-existing pytest failures（orthogonal，不在 Phase 2 root cause 範圍）— Task 11A commit message 已記錄「pytest tests/ 跟 c681e3a8 HEAD 同 7 個 failures，無新 failure」。下個 maintenance window 處理。
4. Phase 4 FE preview UI 重設計（design.md §4 / 5d 預估）：preview 需顯示 ImportWarning chip（normalizer.py 已 emit warnings）+ LA / Component / InventoryItem 三 sub-panel；template-edit 5-tab 第四 tab 必須改讀新表 — 這是 user-facing demo readiness 的關鍵 phase（見 §9 demo gap）。
5. OSCAL export endpoint（design.md Phase 5 / 5d 預估）：round-trip verification 的最後一塊。

6.2 Phase 1 follow-ups（仍未處理，從 2026-05-24-phase1-COMPLETE-SUMMARY.md 延續）

6. API contract implementation_type vs component_type：SspImportTemplateAppService._build_info_systems dict key 改了，Phase 3 e2e 要驗 Excel template 下游沒人依賴舊 key。
7. project_device_route 410-Gone 未實作：tests/test_c3_scope_migration.py::test_gone_response_uses_grc_error_code 用 @pytest.mark.skip，獨立任務。
8. Leveraged delete orphan service-Component：用戶刪 LA 時 linked Component 變 orphan（leveraged_authorization_uid 指向已刪 LA.uid）— Phase 4 FE 重設計時處理。
9. AbstractSspComponentWriteStrategy.write() sys_impl_main_id dead param — Phase 2 Task 11A 刪 base.py 後此 follow-up 自動結案 ✅。

7.1 Task 12 Part 2 — 套件進版 + 主專案 pin 還原（user 拍板才執行）

兩 repo 都還 local，未 push。Push 需 user 明確指示（per CLAUDE.md「push 永遠要 user 明確指示」）。

執行步驟（user 拍板後）：

# 1. jedi-oscal bump version
cd ~/Projects/Jedicogy/module/jedi-python-package/jedi-oscal
# 編輯 pyproject.toml: version = "0.0.18" → "0.1.0"
git add pyproject.toml
git commit -m "chore(jedi-oscal): bump 0.0.18 → 0.1.0 (OSCAL Component/LA/Inventory split)"
# push 到 Nexus（依套件 publish flow）

# 2. 主專案 pin 還原
cd ~/Projects/Billows/Audit-Manager/compliance-manager-be
# 編輯 pyproject.toml：
#   - line ~80 jedi-oscal pin: "^0.0.18" → "^0.1.0"
#   - line ~91 path dep 改回註解（dev-only）
poetry update jedi-oscal
# smoke：python main_app.py 8000 listening + DI 122 modules wired
git add pyproject.toml poetry.lock
git commit -m "chore(ssp-oscal-alignment): bump jedi-oscal 0.0.18 → 0.1.0 + restore pin"

# 3. 兩 repo push（user 明確指示後）
git push origin feature/ssp-oscal-alignment
cd ~/Projects/Jedicogy/module/jedi-python-package/jedi-oscal
git push origin feature/ssp-oscal-alignment

7.2 部署順序（兩 repo 同 deploy unit）

1. jedi-oscal 0.1.0 推 Nexus（先）
2. 主專案 deploy（pin 0.1.0 後）
3. DB migration 已在 Phase 1 跑完（dev DB 確認 + staging / prod 上線時補跑 scripts/sql/2026-05-24-ssp-oscal-alignment-*.sql 4 個檔）

7.3 FE 對齊（提醒）

Phase 4 FE preview UI 是 Phase 1+2 ship 後的後續 task — FE repo 路徑 ~/Projects/Billows/Audit-Manager/compliance-manager-fe，建議切到 FE repo 開新 session 由 FE Claude 主導。Phase 1+2 本身沒動 FE，但 Excel import 412 行為差異會被 FE 既有 error toast 抓到。

Phase 2 Task 12 Part 1 commit (2bd8e7b3) 之後，user 拉 docx import 跑端到端驗證，連續觸發兩個 latent bug：

Hotfix 1 — Bug A：docx confirm 對 module_frame source 沒建 SSP shell（ba0cdd7a）

Hotfix 2 — RLS policy delimiter（d12bd705）

完整 root-cause 寫在 design.md §11.16（RLS）+ 待補 §11.17（Bug A — 本文件下方第 12 段補入）。

⚠️ 3 個未收尾項目，Phase 3/4 接手者開工前先掃過：

L1 — Task 12 Part 2：jedi-oscal 0.0.18 → 0.1.0 bump + Nexus push + 主專案 pin 還原

L2 — Bug B：docx import 5 parties 全 decision=skip → 0 parties 寫入

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

這段是 Phase 3/4 接手者必讀 — 解釋為何 Phase 1+2 完成 ≠ user 看得到 import 結果。

9.1 Phase 邊界對應 user-facing 問題

9.2 為何 Phase 2 完工 user 還是「空白」（template-edit 截圖驗證）

驗證 case：MF 62c31d47-a90e-40e0-98ae-cb0c164a8acc（SSP id=260）

Root cause：template-edit 5-tab 仍是 Phase 0 設計（OLD 三族 entity device / information_system / leveraged）；新表 ssp_components 沒有對應的 tab → 4 個 components 在 FE「不存在」。

驗證 query（密碼請查 .env）：

-- 連 cmmgr@192.168.50.188:25432/guidant_ai_dev
SET app.is_super_admin='t';
-- LA 由 SSP id 查
SELECT id, uid, title FROM oscal.ssp_leveraged_authorizations WHERE ssp_id=260;
-- Components 同上
SELECT id, uid, title, component_type FROM oscal.ssp_components WHERE ssp_id=260;
-- 對比 FE 截圖 → 確認 BE 有資料，差距在 FE 沒讀

9.3 Acceptance criteria 分三層

結論：要做 user-facing demo readiness，先做 Phase 4 收 demo gap；Phase 3 解 Excel import path 但不阻擋 docx demo；Phase 5 是 round-trip 收尾。

本 task arc 全程採 superpowers:subagent-driven-development mode：

Pattern baked into 後續 phase prompt：DB-touching / 大規模 refactor task 開工前，controller 親查 schema + sample data + 看既有 caller 慣例（trust-but-verify pre-flight），再寫 implementer prompt。

詳細版本（含 Phase 4 優先建議 + Bug B/C 開工前必處理）見 docs/features/FR-028-2605-ssp-oscal-alignment/handoff/2026-05-25-phase3-4-handoff.md。下方為精簡版：

你接手 SSP OSCAL Alignment Phase 3 — Excel/Docx 樣板重設計。Phase 1+2 完整 SHIPPED（28 主專案 commits + 18 jedi-oscal commits，全 local）。請按以下順序讀文件：

1. docs/features/FR-028-2605-ssp-oscal-alignment/handoff/2026-05-25-phase1-phase2-FINAL-SUMMARY.md（本文件 — 5 分鐘）
2. docs/features/FR-028-2605-ssp-oscal-alignment/design.md §11.12~§11.15（Phase 2 reconciliation）— 重點 §11.13 Excel parser gap
3. docs/features/FR-028-2605-ssp-oscal-alignment/design.md §3 Phase 3 段（Excel/Docx 樣板重設計 4d）
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：
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：tail -50 log/app.log，預期無 Traceback；pytest tests/test_ssp_docx_import_app_service.py 應綠

Phase 3 §3.X 首要任務：改 Excel parser 輸出 v2-bundle dict shape，恢復 Excel import 從 412 變 200。