# 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 樣板）

---

## 一句話總結

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

---

## 本期完成的 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)
```

---

## 改動範圍

### 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 個次級決策）

---

## 行為差異

### 對既有功能

- ✅ `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`

---

## 規範文件齊全度盤點

| 規範 | 文件 | 狀態 |
|------|------|------|
| 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` | ✅ |

---

## 已知 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 |

---

## 部署 / Handover 注意事項

### dev 環境

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

---

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

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` 精神延伸）。

---

## 下次 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 期間測試需要）

---

## 對話紀錄缺漏

`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` 即可（不二次加工）。