A4 Phase Final SUMMARY — devices / info_systems / leveraged / 控制項 / AO 鉤稽 + SSP 寫入完整化

Phase：A4（Track A：Excel 匯入第四階段） 狀態：BE shipped ✅（Session A→F 共 6 session 全完成） Ship 日期：2026-05-20 Task arc 跨度：2026-05-20 同日 6 session（A 設計 / B plan / C reconciler 骨架 / D reconciler 細節 / E 寫入 pipeline / F 補測試 + 收尾） 依賴本 phase：A5（預覽 UI + Confirm）讀本 phase Step 7 回填的 matched_*_id / match_method

A3 ship 後 Excel/docx flow 的 parties 已走完整 reconcile（exact / normalized / fuzzy 三階段），但 SSP Excel confirm_import 的 其餘 5 個 entity（devices / information_systems / leveraged / catalog controls / assessment objectives）跟 SSP shell（SystemSecurityPlan + SystemCharacteristic + SspSystemImplementation main）仍是 stub log 計數，沒實際落地。

A4 把這段補完：

• Reconciliation 層 — 5 個新 reconciler 建在 A3 BaseReconciliationService 上，加 USER_SELECTED stage 處理樣板的 matched_* 預配對 column，並 retroactive 補 A3 PersonReconciler / OrganizationReconciler
• Write 層 — SSP shell 建立 / 既有 SSP 解析 + 5 WriteStrategy（含 Device / InfoSystem / Leveraged 共用的 AbstractSspImplementationItemWriteStrategy base class）
• App service _write_all_data 重整為 8-step 完整 pipeline（party reconcile → SSP shell → typed dataclass → orchestrator reconcile → party write → 5 entity write → parsed_result 回填 → 統計 return）
• A2 §15.3 整併 — superset flow 的 include_controls 從 A4 ControlReconciler 結果直接反查 catalog，A4 ship 後 subset profile 立刻生效
• A3 retroactive — _dict_to_parties 補 matched_user_label / matched_org_unit_label 傳遞，A3 漏掉的樣板 lookup col USER_SELECTED stage 一次補完

詳細 reconciler 演算法 / pipeline 步驟見 design-A4.md §5 / §6.1。

compliance-manager-be（branch feature/ssp-import-export-phase2）

A4 BE 共 10 個實作 commit（feat × 8 + test × 1 + docs E 收尾 × 1）+ 4 個 docs handoff/SUMMARY commit。

jedi-* 套件

不動（design §10 鎖定範圍）。jedi-oscal 維持 path-dep（feature 整體完工才一次 bump version + 推 Nexus）。

compliance-manager-test

T10 cucumber 拍板跳過 — 留 follow-up F-A4-cucumber（理由見 §5）。

新建檔案

Domain layer — reconciliation/（5 個 + 1 個 helper）：

domain/oscal/service/reconciliation/
├── catalog_control_reconciler.py        # 二階段 (USER_SELECTED + EXACT/NORMALIZED on control_id)
├── assessment_objective_reconciler.py   # 走父 control 配對，reconcile_with_control_map
├── device_reconciler.py                 # 三階段 (USER_SELECTED label / EXACT IP+name / fallback)
├── information_system_reconciler.py     # 三階段 + system_owner label 反查
├── leveraged_reconciler.py              # 三階段 (USER_SELECTED party / EXACT name / FUZZY_NAME_PREFIX)
└── ssp_entity_orchestrator.py           # facade — 5 reconciler dispatch by entity type

Domain layer — write_strategy/（5 strategy + 1 base）：

domain/oscal/service/write_strategy/
├── base.py                                       # AbstractSspImplementationItemWriteStrategy
├── control_write_strategy.py                     # 寫 control_implementations，返 ctrl_impl_id_map
├── ao_write_strategy.py                          # 寫 control_impl_objectives，需 ctrl_impl_id_map 注入
├── device_write_strategy.py                      # kind='hardware'（繼承 base）
├── information_system_write_strategy.py          # kind='system'（繼承 base）
└── leveraged_write_strategy.py                   # kind='leveraged-authorization'（繼承 base）

Tests（17 個 A4 test 檔，~165 test）：

tests/test_a4_*.py
├── test_a4_parsed_entity_fixtures.py             # 共用 fixture
├── test_a4_reconciliation_helpers.py             # stage 0 dispatch / by-key 對齊
├── test_a4_reconciliation_orchestrator.py        # facade dispatch
├── test_a4_reconciliation_device.py              # 三階段 + boundary
├── test_a4_reconciliation_information_system.py  # 三階段 + system_owner
├── test_a4_reconciliation_leveraged.py           # fuzzy + suffix strip
├── test_a4_reconciliation_catalog_control.py     # 二階段
├── test_a4_reconciliation_assessment_objective.py # reconcile_with_control_map
├── test_a4_a3_retroactive.py                     # A3 retroactive PersonReconciler / OrganizationReconciler
├── test_a4_a2_integration.py                     # A2 §15.3 superset include_controls 反查
├── test_a4_ssp_shell.py                          # _create_ssp_shell / _resolve_existing_ssp_shell
├── test_a4_write_strategy_base.py                # base template method
├── test_a4_write_strategy_control.py             # 寫 control_implementations
├── test_a4_write_strategy_ao.py                  # 寫 control_impl_objectives
├── test_a4_write_strategy_device.py              # 繼承 base
├── test_a4_write_strategy_information_system.py  # 繼承 base
├── test_a4_write_strategy_leveraged.py           # 繼承 base
├── test_a4_write_all_data_pipeline.py            # 8-step pipeline + _dict_to_* + by-key 對齊
├── test_a4_boundary_cases.py                     # T9 boundary（reconciler 多 candidate / abbr 解析 / Control+AO empty list）
└── test_a4_reconcile_to_write_integration.py     # T9 真實 reconciler+strategy 整合

改動既有檔案

design-A4.md §11.1 已含 Session C / D / E 共 16 條偏差紀錄。Session F (T9 + T11) 沒新偏差 — T9 純補 test 行為一致，T11 純文件，§11.1 不再追加。

F-A4-cucumber 撰寫前置條件（env 配齊那天執行）

跨 repo work — 在 ~/Projects/Billows/Audit-Manager/compliance-manager-test/ 開 branch。

前置條件：

1. GitLab CI pipeline 配齊（A1/A2/A3 cucumber 都同期 partial ship / pending — 同期 4 phase 都等 env 配齊）
2. A4 fixture seed helper 配齊：device 'Web-01' / info_system 'ERP' / Party 'AWS GovCloud' / catalog 'AC-1' 等

範圍：新建 features/regression/module-frame/06-ssp-excel-import-entity-match.feature 含 5 scenarios：

• control_id 對到 catalog 內 control (exact)
• device matched_device 下拉選定 (user_selected)
• info_system name 對到 tenant entity (exact)
• leveraged provider fuzzy 對到 Party (fuzzy_name_prefix)
• AO objective_id 父 control 配到後自身配到 (exact)

step + page object 沿 A3 cucumber pattern（feature/a3-ssp-party-match-regression ship 在 commit 27e52fe）。

partial ship pattern：env 配齊那天可一次性補完 A1 / A2 / A3 / A4 共 4 phase cucumber。

跳 T10 理由（2026-05-20 拍板）

• GitLab CI pipeline 配齊時程 user 不清楚 → 寫 cucumber 也只是 dead code
• A1 / A2 / A3 cucumber 都同步 partial ship / pending — 同期 4 phase 都等 env 配齊
• 留 follow-up F-A4-cucumber：env 配齊那天一次性補 4 phase 比較有效率

6.1 套件狀態

• jedi-oscal：維持 path-dep（pyproject.toml dev-path 改動不 commit；feature 完成才一次 bump version + 推 Nexus）
• jedi-auth / jedi-common：A4 不動 — 維持 Nexus pin
• 主專案 pyproject.toml：A4 期間 dev-path 改動 working tree 仍未 commit（正常 — Phase 2 整體完工才一起還原 + commit）

6.2 BE 重啟需求

A4 改動了 app service / DI Container / domain layer（app/oscal/service/ssp_excel_import_app_service.py + di_containers/oscal/oscal_containers.py + 11 個新 domain class）— BE 沒 hot reload，下次 manual smoke 測 A4 confirm flow 前必先重啟：

lsof -ti:8000 | xargs kill -9
nohup poetry run python main_app.py > /dev/null 2>&1 &

6.3 DB / Migration

• A4 無 schema 異動（依賴 A0 / A0.1 既有結構 + A0.1 ship 的 ssp_system_implementations main + ssp_system_implementation_items）
• oscal_parties / oscal_responsible_parties schema 不動
• system_security_plans / system_characteristics / control_implementations / control_impl_objectives schema 不動

6.4 後續 phase 開工建議

A4 完工後：

• A5 phase（預覽 UI + Confirm 寫入）— 讀 A4 Step 7 回填的 matched_*_id / match_method / match_confidence；fuzzy 拍板攔截路徑
• Track B（SSP 匯出 B1-B6）— 可獨立起手，與 A5 解耦

下一個決策點：

• (a) 走 A5 phase（接續 Track A 完成 Excel 匯入全程）
• (b) 跳 Track B（SSP 匯出 B1-B6；可平行 / 換 thread）
• (c) 暫停評估其他 priorities

• 顯式 git add <file>，禁 -am / -A（10 個 BE feat/test commit + 4 個 docs commit 全用 explicit list）
• Commit 含 Co-Authored-By: Claude Opus 4.7 (1M context) footer
• jedi-* 不動（package source unmodified）
• pyproject.toml dev-path 改動不 commit（working tree 持續未 commit ✅）
• DDD 嚴格分層 — 11 個新 domain class 純 domain layer 不接 session；reconcile / write 串接點在 app service @transaction scope 內
• T8 / T9 ship 後跑全套 a3+a4+a2 ssp_excel pytest（282 passed / 0 regression）
• BE 重啟需求已標 §6.2
• 不寫 docstring / 註解除非真有 non-obvious 的 why
• design-A4.md §11.1 偏差段不空 — 16 條偏差條目 + 已對齊條目 ship
• Handoff 文件統一放 docs/features/<feature>/handoff/（CLAUDE.md 2026-05-20 新規）
• 階段性 commit 不用問 — Session F 直接 commit 不停下問
• T6 / T8 偏差（plan 假設 vs 實際）逐條進 §11.1.10-16
• T9 純 test commit 用 type=tweak（行為一致）

✅ A4 phase 完整 ship — 6 session（A→F）on schedule，T10 cucumber 拍板跳過留 follow-up F-A4-cucumber

進入 A5 phase / Track B 條件已就緒：

• 5 個 reconciler + 5 個 WriteStrategy + SSP shell + 8-step pipeline + DI 19 dep wiring + ~165 個 a4 test 全綠
• A5 phase UI 需要的 matched_*_id / match_method / match_confidence 全部由 Step 7 回填到 parsed_result
• import_summary response 含 ssp_id / sys_impl_main_id / 5 個 *_written 計數，FE 可直接讀

A4 累計交付：

• 10 個 BE 實作 commit（feat × 8 + test × 1 + docs E 收尾 × 1）
• ~165 個 a4 test 全綠（含 Session E 58 + T9 補 12）
• 0 regression（a3+a4+a2 ssp_excel 282 全綠）
• 16 條 design §11.1 偏差條目 完整保留決策軌跡
• 2 個 changelog（feat write-pipeline + tweak boundary tests）

實際耗時 6 session 跟 design §12 預估的 6 session 完全對齊。