Phase 2 A0.1 執行收尾 — 完整 ship 報告

日期：2026-05-19 本檔角色：A0.1 task arc 收尾總結（執行 session 完成） 前置文件：00-plan-handoff.md 是設計階段的 handoff，本檔是執行階段的收尾 狀態：A0.1 shipped ✅

A0.1 結構重整補丁（rename items + 新建 main / join + column rename + caller 改寫）按 plan 全跑完，8 個 commits 跨 2 repos + 1 個 device_id e2e 補丁 commit，所有 unit test 全綠，DB schema / DI / yaml 序列化全驗證，主 BE smoke 因環境問題改 partial smoke 也通。

1. 執行 SQL Migration

scripts/sql/2026-05-19-ssp-system-implementation-restructure.sql 已在 dev DB 跑通：

• 既有表 rename system_security_plan_system_implementations → ssp_system_implementation_items
• Column rename information_system_id → system_characteristic_id
• 新建 main ssp_system_implementations（129 個 distinct scope → 129 rows backfill）
• 新建 join ssp_inventory_item_components
• Items 加 system_implementation_id NOT NULL FK + 140 筆全部補齊

2. 10 個 Task 全部 ship

3. A0.1 e2e 驗證 + 1 個 follow-up fix

驗證（user 提供 SSP id=244, AP cd128dce-...）：

• AP → SSP 串接 / project 229 / 4 人 / 3 設備 / 3 系統都對齊 UI
• A0.1 三表 main(136) / items(168-170) / FK 全部正確寫入
• 發現：items 的 device_id 全 NULL（A0 既有 caller 忘了填）

follow-up fix（同日 ship）：

• 主 BE 6deacef — project_device_mapping_service.add() 加 device_id=device_entity.id
• scripts/sql/2026-05-19-backfill-ssp-system-implementation-items-device-id.sql 已執行 → UPDATE 135 筆 + 10 筆 unmatchable 保留 NULL

4. 文件交付

jedi-oscal（6 commits, 全 path-dep 未推 Nexus）

4666091 refactor(ssp-system-impl): yaml_mapper 加 main block-level + implemented-components
8e3e58b feat(ssp-system-impl): 新增 inventory_item_components M:N join 表完整 stack
d2178c1 feat(ssp-system-impl): items 表加 system_implementation_id NOT NULL FK + relationship to main
c0fcae9 refactor(ssp-system-impl): items column rename information_system_id → system_characteristic_id
cc65e3b feat(ssp-system-impl): 新增 main 表 OscalSspSystemImplementation 完整 stack
762d8fc refactor(ssp-system-impl): rename items stack to Ssp* + _items suffix

主 BE（3 commits）

6deacef fix(associations): ProjectDeviceMappingService 寫 SSP item 補填 device_id soft FK
87126ab docs(ssp-import-export-phase2): A0.1 shipped — changelog + tracker + design §11
eb9fa7e fix(ssp-system-impl): 主 BE caller 改寫支援 main 表 + 對齊新 class 命名

累計 9 commits（不含 Task 9 之前的 design / plan / SQL handoff commits）。

oscal.ssp_system_implementations         129 rows (1:1 per SSP scope)
oscal.ssp_system_implementation_items    140 rows (全部 system_implementation_id 補齊)
oscal.ssp_inventory_item_components        0 rows (預期 — 等 caller / UI 觸發)

Hardware items device_id backfill 後:
  hw_total=145, hw_has_device=135, hw_null_device=10 (unmatchable)

1. yaml_mapper 簽章 backward-compat — items_list 維持第一 positional，避免破壞既有 7 個 yaml_mapper test
2. _clone_system_implementations 用 SSP relationship — 直接 old_ssp.system_implementations，不另建 old_main → items 反向 relationship
3. 9 個 OSCAL extension 欄位 clone — 7 個 getattr 安全取，2 個 scope_type/scope_id hardcode
4. BE smoke partial — 完整 boot 撞 gitlab/github env 環境問題（非 A0.1），改 DI / service / DB sanity 4 項驗證
5. 3 個 minor robustness follow-up — main audit created_user=None、orphan main、yaml implemented-components 排序

對 dev DB 已執行

• ✅ scripts/sql/2026-05-19-ssp-system-implementation-restructure.sql
• ✅ scripts/sql/2026-05-19-backfill-ssp-system-implementation-items-device-id.sql

對 staging / production

• ⏸ 上述 2 個 SQL migration 需要 user 在對應環境執行
• ⏸ jedi-oscal 仍在 path-dep 模式，要正式 deploy 前需：
  1. jedi-oscal pyproject.toml bump version
  2. 推 Nexus
  3. 主 BE pyproject.toml 改回 pin Nexus 版本
  4. poetry update jedi-oscal

BE 重啟（user 在配齊 GITLAB_*/GITHUB_PRIVATE_TOKEN env 環境）

lsof -ti:8000 | xargs kill -9
cd ~/Projects/Billows/Audit-Manager/compliance-manager-be
set -a; source .env; set +a
nohup poetry run python main_app.py > /dev/null 2>&1 &

兩條 parallel paths

A1：Excel 樣板設計 + 下載

• 中型 phase（design 段落 + plan，不獨立 brainstorm）
• 依賴 A0.1（已 ship ✓）
• 範圍：產出 9 大資料領域（metadata / 單位 / 人員 / 設備 / 資訊系統 / leveraged / 控制項 / AO / 程序書）的 Excel 樣板 + 下載 API

B1：Docx 樣板 + generator 骨架

• 中型 phase
• 依賴 A0.1（已 ship ✓）
• 範圍：SSP docx 匯出格式樣板 + python-docx generator 基礎

兩條可平行起手，依 user 優先級決定。

建議

• 接手前讀本 SUMMARY.md（執行階段全脈絡）+ 00-plan-handoff.md（設計階段脈絡）
• A1 or B1 開工前先 brainstorm scope（中型不必但建議先列範圍）
• 建議先看 docs/features/FR-011.2-2605-ssp-import-export-phase2/requirement-understanding.md §3、§4 確認最新 scope

• 顯式 git add <file>，禁 -am / -A — 全 9 commits 都遵守
• 所有 commits 含 Co-Authored-By: Claude Opus 4.7 (1M context) footer
• jedi-oscal 仍 path-dep，未推 Nexus
• pyproject.toml dev-only path-dep 改動沒被 commit（仍在 working tree）
• BE 重啟必 kill -9（過程中遵守）
• SQL migration 帶日期標記 + 帳號用 cmmgr
• 重型 task (1 / 6 / 7) 過雙 reviewer（spec + code quality）
• 沒做未授權的破壞性操作

A0.1 是 A0 ship 後 e2e 校正的補丁 — 從「items 表名稱誤導 / 缺 main / 缺 join / 鉤稽路徑重疊 / 命名不一致」5 個結構問題收口到「items + main + join 三層完整 OSCAL block 鏡像」。execution 階段照 plan 跑完 10 個 task 沒大偏差，最大的驚喜是 e2e 驗證階段意外發現了 A0 既有 device_id caller 沒填的 bug 並順手修正。

A0.1 task arc 完整收尾。Phase 2 的基礎建設層完成，後續可開始 Track A（Excel 匯入）或 Track B（SSP 匯出）的具體 phase。