↑ 需求首頁 ⌂ 需求中心

Phase 2 A0 收口報告 / 明天 session 交接文件

日期：2026-05-18 Phase：A0（OSCAL system-implementation 表擴充，Phase 2 第一個 phase） 狀態：✅ shipped，working tree 乾淨（除 pyproject.toml 是 dev-only 不該 commit） 下次 session：開始 A1（Excel 樣板）或 B1（Docx 樣板）

§1

一句話總結

擴充既有 oscal.system_security_plan_system_implementations 表（不新建 mirror 三表），讓 devices / information_systems / leveraged services 三類資料能進 OSCAL system-implementation 段，並支援 scope_type 區分合規資源庫 / SSP 雙來源。為 Phase 2 後續所有 phase 打地基。

§2

本期完成的 commits

compliance-manager-be（主專案）

a1b80cc  fix(ssp-system-impl): 既有 caller 補 scope_type/scope_id (Task 10 fix)
60a4a2e  docs(ssp-import-export-phase2): A0 shipped — changelog + tracker (Task 11)
e73b1aa  tweak(ssp-system-impl): A0 regression smoke test (Task 10)
c4804d7  tweak(ssp-system-impl): SQL schema migration 9 欄 + ssp_id nullable + 140 筆 migration (Task 3)
e314e46  docs(ssp-import-export-phase2): A0 implementation-plan 完成 (Phase 0 plan)
e5213c9  docs(ssp-import-export-phase2): 啟動 Phase 2 task arc + A0 design (Phase 0 setup)

jedi-oscal monorepo（branch feature/ssp-import-export-phase2，未推 Nexus）

dbb3d7c  feat: YAML mapper 三分支 OSCAL 序列化 (Task 9)
96f31e7  feat: DTO 擴充 (Task 8)
e08fa23  feat: Repository 3 query methods (Task 7)
267aca6  feat: Mapper round-trip 9 欄位 (Task 6)
5c48fe4  feat: Entity + QueryEntity 9 欄位 (Task 5)
1ba6554  feat: ORM 9 cols + ssp_id nullable (Task 4)
afe7035  feat: SystemImplementationType + LEVERAGED_AUTHORIZATION (Task 2)
§3

改動範圍

DB Schema (PostgreSQL)

oscal.system_security_plan_system_implementations 加 9 個欄位、改 1 欄 nullable、加 3 個 index、補 table COMMENT、140 筆既有資料 migration 補 scope。

程式碼

  • jedi-oscal 8 個層全部擴充（ORM/entity/query_entity/repo interface+impl/mapper/yaml_mapper/DTO/enum）
  • 主專案 2 個 caller 補 scope_type='ssp' + scope_id
  • 主專案新增 1 個 regression smoke test

文件

  • design.md / implementation-plan-A0.md / requirement-understanding.md (v4) / README.md tracker
  • changelog: docs/changelog/2026-05-18-tweak-ssp-system-impl-extension.md
  • analysis: docs/analysis/2026-05-18-ssp-system-impl-extend-vs-new-tables.md（v3→v4 架構抉擇 + 3 個次級決策）
§4

行為差異

對既有功能

  • ✅ project_device_mapping_service 仍能寫入新 device mapping（自動帶 scope_type='ssp'）
  • ✅ ssp_versioning_service 仍能 clone SSP 版本（cloned rows 自動帶 scope_type='ssp' + scope_id=new_ssp.id）
  • ⚠️ OSCAL 匯出輸出 shape 改變：SystemSecurityPlanYamlMapper._system_implementation_to_dict 依 implementation_type 分流到 inventory-items / components / leveraged-authorizations 三段（過去全塞 components）— 下游 OSCAL consumer 須留意

新增能力（A1 之後才會用上）

  • 支援 scope_type='module_frame' 紀錄（system_security_plan_id 可 null）
  • 鉤稽 tenant 層 device / information_system（device_id / information_system_id soft FK）
  • OSCAL leveraged-authorization 欄位（party_uuid / date_authorized）
  • 3 個新 query method：list_by_scope / find_by_device_id / find_by_information_system_id
§5

規範文件齊全度盤點

規範 文件 狀態
Changelog (type=tweak) docs/changelog/2026-05-18-tweak-ssp-system-impl-extension.md ✅
Issue — 無（feature 不是 bug）
Analysis（架構抉擇） docs/analysis/2026-05-18-ssp-system-impl-extend-vs-new-tables.md ✅
Tracker docs/features/FR-011.2-2605-ssp-import-export-phase2/README.md ✅ A0 row → shipped
Conversation history docs/conversation-history/2026-05-18/ssp-import-export-phase2/ ⚠️ 只有 ca3066a1.md 涵蓋 spec 分析階段（10:22-14:53），A0 實作階段 16:00+ 對話沒被 export — 後續需要時手動補 export
Summary (本檔) SUMMARY.md ✅
§6

已知 follow-up

# 項目 來源
1 responsible_party (varchar) 欄位資料遷移到 oscal_responsible_parties polymorphic 表 design.md §3.2 / N10
2 既有 enum 值 hardware 是否完全淘汰改用 inventory-item requirement-understanding §7.4 N8 衍生
3 docx parser 擴充到 devices / information_systems 鉤稽（寫入鏡像表） Q3 / 列入「最後統整優化清單」
4 jedi-oscal 套件 bump 版本 + 推 Nexus 整個 Phase 2 完工後一次性做（CLAUDE.md jedi-* 進版流程）
5 A0 minor code review 觀察（test 斷言不全 / Optional vs DB NOT NULL 註解） Task 4/5/6/9 reviewer 提的 minor 非阻塞項
6 poetry.dev-dependencies deprecation warning（改用 poetry.group.dev.dependencies） Task 1 verify import 時看到的 warning
§7

部署 / Handover 注意事項

dev 環境

  • pyproject.toml 仍在 path dependency mode（指本地 jedi-oscal source）— 不 commit，feature 完工才還原 pin 版本
  • BE 重啟才能讓 jedi-oscal 改動生效（沒 hot reload）： 
    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 &

其他環境

  • 還沒部署 — staging / prod 上 A0 SQL migration 尚未跑（只在 dev DB 跑過）
  • jedi-oscal 還沒推 Nexus，pin 0.0.16 在 production 不含 A0 改動
  • 整個 Phase 2 完工才正式 release
§8

過程中的失誤紀錄（供下次自警）

  1. 架構誤判：v3 design 主張新建 OSCAL mirror 三表 + 廢既有表，沒先 grep 既有 caller 也沒查 DB 既有資料就下結論。發現「既有 140 筆 + 既有 caller 在用」後 v4 校正成擴充方案。教訓：架構決策前必先 grep + SELECT DB 確認既有真實狀態（對應 memory feedback_verify_db_state_before_writing_fixes）。

  2. commit sweep：Task 10 commit 沒先 git status --short 確認 staged 區，把 user 預先 staged 的 conversation-history docs 一起 sweep 進來。user 接手 reset 重做後，我又在後續 reset 時不小心讓 caller fix 沒進 git（誤以為已 commit）。最後 a1b80cc 才真正落地。教訓：commit 前必先 git status --short 看 staged 區內容，禁止 commit 不是自己 add 的檔案（對應 memory feedback_subagent_explicit_git_add 精神延伸）。

§9

下次 session 開工建議

1. 先讀以下檔案（依序）

  1. docs/features/FR-011.2-2605-ssp-import-export-phase2/README.md — Phase 2 master tracker（A0 已 shipped，下一步 A1 / B1）
  2. docs/features/FR-011.2-2605-ssp-import-export-phase2/requirement-understanding.md — 全 phase scope（v4 校正後完整版）
  3. 本檔（SUMMARY.md） — 對 A0 收口理解
  4. docs/analysis/2026-05-18-ssp-system-impl-extend-vs-new-tables.md — A0 為什麼這樣做

2. 選下一個 phase

  • A1 (Excel 樣板設計 + 下載)：中型 phase，不獨立 brainstorm，直接寫 design 段落 + plan。比較適合上午精神好時開
  • B1 (Docx 樣板拆解 + python-docx generator 骨架)：中型 phase，同樣不獨立 brainstorm
  • 兩條 track 可平行 — 選一條開即可

3. 開工前必做

  • 切到 branch feature/ssp-import-export-phase2（已 checkout）
  • 確認 jedi-oscal 還是 path dep（pyproject.toml 內 [tool.poetry.dev-dependencies] 段沒被誤還原）
  • BE 重啟（讓 A0 改動生效，跑 dev 期間測試需要）
§10

對話紀錄缺漏

docs/conversation-history/2026-05-18/ssp-import-export-phase2/ca3066a1.md 只到 14:53，缺：

  • A0 brainstorm 收斂剩餘段（15:00-16:00 大致時段）
  • A0 implementation-plan 撰寫
  • Task 0~10 dispatch subagent + review 全程
  • Task 10 caller fix 架構討論
  • Task 11 + commit sweep recovery

如下次 session 需要這段歷史，請手動 export 補入 docs/conversation-history/2026-05-18/ssp-import-export-phase2/ 下，命名 <session-uuid>.md 即可（不二次加工）。