# SSP OSCAL Alignment — Phase 3 DONE / Phase 4 WIP SUMMARY — 2026-05-25

| 項目 | 內容 |
|---|---|
| Phase 範圍 | **Phase 3 全完工**（§3.1 + §3.2 + §3.3）+ **Phase 4 部分完工**（BE read endpoints + FE 新 tab read-only + BE write endpoints WIP）+ **Phase 5 已 defer**（user 拍板等定案）|
| 日期區間 | 2026-05-25（單日全程）|
| Branch（兩 repo 一致）| `feature/ssp-oscal-alignment` |
| 主專案 local commits | **28**（baseline `d12bd705` Phase 1+2 收尾後）|
| 主專案 working tree | `M pyproject.toml`（path-dep dev-only，**永遠不 stage**）|
| FE local commits | **1**（baseline `e873fae`）|
| FE working tree | clean |
| Test 狀態 | BE 全相關 test suite 全綠（91 docx adapter + 136 excel template/parser + 121 ssp excel/docx import + 17 v2_bundle/smoke）|
| 下一步 | **新 session 接手 Phase 4 剩餘工**（FE inline CRUD / 移除舊 tab / 5-tab 重組 / Phase 4.4 FE Excel preview 對齊 v3 + 接 BE write endpoints route 端） |

---

## 0. 一句話收尾

**Phase 3 v3.0.0 OSCAL-aligned 重組 ship 完**（Excel + Docx 雙 import path），FE 端新 tab 已能看 BE component/LA/inventory 資料；但**Phase 4 inline CRUD 跟移除舊 tabs 沒做**（user 仍用舊 tabs 編輯 hardware/info_system），且 **Phase 3.1 v3.0.0 Excel 樣板 ship 後 FE Excel preview 會顯示空** — Phase 4.4 「Reuse Excel preview component」必須在 Phase 4 collect 收掉。

---

## 1. 本期 commits 清單（主專案，10 commits）

| Commit | 摘要 |
|---|---|
| `05ae6a19` | feat: Phase 4 BE WIP — SspComponentsAppService CRUD methods |
| `910b7f5a` | chore: Phase 3.3 — regenerate reference templates v3.0.0 |
| `c115b7bc` | feat: Phase 3.2 — Docx components + inventory_items extractors |
| `f7eaa09f` | feat!: **Phase 3.1 — Excel sheet OSCAL-aligned 重組 v3.0.0** |
| `475fb544` | docs: defer Phase 5 OSCAL Export |
| `49eed533` | feat: Phase 4 BE — /ssp/<uid>/components + /ssp/<uid>/inventory-items read endpoints |
| `59c1378f` | test: Phase 3 — integration smoke for v2-bundle pipeline |
| `ca7f5bd6` | docs: 補登 Phase 2 implementation plan 文件入版 |
| `8ac3e35b` | fix: Phase 3.X — Excel parser 輸出 v2-bundle dict shape，恢復 200 |
| `8e8d5624` | fix: Phase 3 Bug C — v2-bundle confirm path 套 content_overrides |

**FE repo 1 commit**：`bd23047` feat: Phase 4 FE — new「元件 + 授權 + 資產」第四 tab

**Memory 更新**：`~/.claude/projects/-Users-chouraymond-Projects-Billows-Audit-Manager-compliance-manager-be/memory/feedback_cross_repo_read_claude_md_first.md`（新）+ `feedback_be_fe_version_alignment.md`（修正不再勸切 session）+ MEMORY.md index 更新

---

## 2. Phase 3 + Phase 4 完工 / 未完工 速覽

### Phase 3 ✅ DONE

| 子段 | 完工內容 | Commit |
|---|---|---|
| §3.X transitional | v1 (devices/info_systems/leveraged) → v2-bundle dict shape mapping，恢復 Excel import 412 → 200 | `8ac3e35b` |
| §3.1 Excel sheet 重組 | TEMPLATE_VERSION v2.6.0 → **v3.0.0** major bump；移除設備/資訊系統/外部利用服務；新增 資產清冊（InventoryItem）/ 元件清冊（Component）/ 利用授權（LeveragedAuthorization）三 OSCAL-aligned sheets | `f7eaa09f` |
| §3.2 Docx extractor | extract_components_table + extract_inventory_items_table + adapter wire | `c115b7bc` |
| §3.3 Reference regen | regen v3.0.0 sample xlsx；刪 v2.6 reference | `910b7f5a` |

### Phase 4 部分 — DONE / WIP / TODO 一覽

| 子段 | 狀態 | 內容 |
|---|---|---|
| BE read endpoints | ✅ DONE | `/ssp/<uid>/components` + `/ssp/<uid>/inventory-items` GET（pre-join LA title / implemented_components）|
| FE 新 tab read-only | ✅ DONE | `SspComponentsLeveragedInventoryTab.vue`（DataTable + card list + DataTable）插入 tab 4，舊 tabs 標「(舊)」|
| BE write endpoints — components CRUD | ⚠️ **WIP** | App service `add_item/update_item/delete_item` 已寫（`05ae6a19`），routes 還沒暴露 POST/PUT/DELETE |
| BE write endpoints — inventory_items CRUD | ❌ TODO | 同 components 寫 `add_item/update_item/delete_item` 在 `ssp_inventory_items_app_service.py` + route POST/PUT/DELETE |
| FE inline CRUD on new tab | ❌ TODO | Add/Edit/Delete dialogs × 3 entities（components / LA / inventory_items）|
| 移除舊 3 tab | ❌ TODO | SspTabPanel.vue 移除 設備(舊)/資訊系統(舊)/外部利用服務(舊) + 刪 `LeveragedSection.vue`/`ModuleFrameSspDevicesPanel.vue`/`ModuleFrameSspInfoSystemsPanel.vue` |
| Phase 4.1 5-tab 完整結構 | ❌ TODO | 受評標的（SC）拆獨立 tab / 單位+參與人員合併 / 加控制項 tab |
| **Phase 4.4 Reuse Excel preview component** | ❌ **TODO 緊迫** | Phase 3.1 v3.0.0 樣板 ship 後 FE Excel preview (SheetPreviewDevices/InfoSystems/Leveraged) 讀 v1 keys → 顯示空。要 generalize 成 v2-bundle keys |
| i18n keys 從 fallback 移正規 namespace | ❌ TODO | Phase 4 完整 UX 收尾 |
| Excel app service `_apply_content_overrides` 接 v3 keys | ❌ TODO | FE Excel preview 改完送 v3 keys 後生效 |

---

## 3. 行為差異對使用者影響（Phase 3 collateral）

### 3.1 Excel template `v2.6.0` → `v3.0.0` BREAKING

- v2.x 樣板被 parser 拒絕（`GRC_EXCEL_TEMPLATE_VERSION_UNSUPPORTED`），user 須重新下載 v3.0.0 樣板
- 新樣板 sheet 結構：`基本資料 / 受評標的 / 單位 / 參與人員 / 利用授權 / 元件清冊 / 資產清冊 / 控制項與AO / 程序書`
- 舊 in-flight v2.x parse_jobs 在 DB 內仍可走 confirm（`derive_v2_bundle_keys` 對 v1 keys mapping 兼容）；只有上傳新檔案會強制 v3.0.0

### 3.2 v3.0.0 Excel 上傳後 FE Excel preview 會空（**最緊迫 follow-up**）

- BE parser 現輸出 `components` / `leveraged_authorizations` / `inventory_items` keys
- FE `SheetPreviewDevices.vue` / `SheetPreviewInfoSystems.vue` / `SheetPreviewLeveraged.vue` 還讀 `devices` / `info_systems` / `leveraged` keys → 顯示空
- 必須 Phase 4.4 收掉

### 3.3 docx import 走新 path（樣板 .docx 還沒加 H2 section 時 fallback OK）

- adapter `adapt_to_bundle()` 新加 `extract_components_table` + `extract_inventory_items_table` 呼叫
- 樣板 .docx 若還沒加 「H2 System Components」/「H2 Hardware Maintenance」section → extractor 返 [] 不影響既有 T6 (CSP/CSO) / T7 (Category) 路徑
- 樣板加表編輯（圖形 Word）由 user 自己做；code 端已 ready

---

## 4. 規範文件齊全度

| 項目 | 路徑 | 狀態 |
|---|---|---|
| design.md §3 階段表 + §5 banner Phase 5 defer | `docs/features/FR-028-2605-ssp-oscal-alignment/design.md` | ✅ `475fb544` |
| design.md §11 reconciliation 新增 entries（§11.18~§11.21 ※TODO）| 同上 | ❌ 下個 session 補 |
| implementation-plan-phase2.md 結尾 Phase 5 defer 註 | `docs/features/FR-028-2605-ssp-oscal-alignment/implementation-plan-phase2.md` | ✅ `475fb544` |
| Phase 1+2 FINAL SUMMARY Phase 5 defer 標 | `2026-05-25-phase1-phase2-FINAL-SUMMARY.md` | ✅ `475fb544` |
| 本 SUMMARY | `docs/features/FR-028-2605-ssp-oscal-alignment/handoff/2026-05-25-phase3-DONE-phase4-WIP-SUMMARY.md` | ✅ 本文件 |
| Changelog (batch 本 phase) | `docs/changelog/2026-05-25-phase3-phase4-wip.md` | ❌ 下個 session 補 |
| Conversation history JSONL extract | `docs/conversation-history/2026-05-25/ssp-oscal-alignment-phase3-4/` | ❌ 下個 session 補 |

---

## 5. 已知 follow-ups（Phase 4 收尾必收）

### L1 — Phase 4 BE write endpoints route 端 + inventory_items CRUD

`05ae6a19` 加了 `SspComponentsAppService` 的 `add_item/update_item/delete_item`，但 routes 還沒對外暴露 POST/PUT/DELETE，且 `SspInventoryItemsAppService` 沒對應 CRUD。

需做：

1. `api/oscal/routes/ssp/ssp_components_route.py`：
   - `SspComponentsListResource` 加 `post`
   - 新加 `SspComponentsDetailResource` class（`put` + `delete`）
   - `api/oscal/__init__.py` add_resource 新 detail route
2. `app/oscal/service/ssp_inventory_items_app_service.py`：複製 components CRUD pattern
3. `api/oscal/routes/ssp/ssp_inventory_items_route.py`：同樣 list + detail route

### L2 — Phase 4 FE inline CRUD on new tab

`SspComponentsLeveragedInventoryTab.vue` 目前是純展示。要加：

- 三個 Add/Edit dialogs × 三 entities（components / LA / inventory_items）
- Form validation（component_type 14 enum / impact_level 4 enum / required fields）
- LA dropdown 選擇器 within component edit（leveraged_authorization_uid FK link）
- Multi-select chip picker for inventory_items.implemented_component_uids
- 串 SspService.{create,update,delete}{Components,Inventory,Leveraged} 方法（已有 listLeveraged / updateLeveraged 等，需檢視齊全度）

### L3 — Phase 4 移除舊 3 tab + 廢棄 vue 元件

新 inline CRUD 上線後：

1. `SspTabPanel.vue` 移除 tab 5/6/7（設備舊 / 資訊系統舊 / 外部利用服務舊）
2. SECTION_TAB_MAP 收回到只剩新結構
3. 刪 `src/components/grc/ssp/SspLeveragedSection.vue`
4. 刪 `src/components/grc/ModuleFrameSspDevicesPanel.vue` / `ModuleFrameSspInfoSystemsPanel.vue`（或標 deprecated 待 MF template-edit 確認也不用）
5. project-planning.json 移除 `section.scope_devices` / `scope_info_systems` / `leveraged` keys
6. count.devices / count.infoSystems / count.leveraged 從 SspTabPanel state 移除

### L4 — Phase 4.1 5-tab 完整結構

設計 §4.1：`[基本資料][受評標的][參與人員][元件+授權+資產][控制項]`

需做：

1. 受評標的（SC）從 `SspBasicSection.vue` 拆出 → 新 `SspSystemCharacteristicSection.vue` 獨立 tab
2. 單位 + 參與人員 合併 → 新 `SspPartiesSection.vue`（或 ModuleFramePartiesPanel 加 mode 切換）
3. 加控制項 tab — 可指向既有 controls page，或 inline panel 在 ssp edit view 內

### L5 — **Phase 4.4 Reuse Excel preview component（緊迫）**

Phase 3.1 v3.0.0 樣板 ship 後 FE Excel preview 會空。需做：

1. Excel preview 路由：`src/views/module-frame/ImportExcelPage.vue` 或同等
2. 改 `SheetPreviewDevices.vue` / `SheetPreviewInfoSystems.vue` / `SheetPreviewLeveraged.vue`：
   - 讀 v2-bundle keys：`components` / `inventory_items` / `leveraged_authorizations`
   - 或 generalize 三檔成單一 `SheetPreviewComponents.vue` / etc.
3. Excel app service `_apply_content_overrides._ROW_OVERRIDE_SHEETS` 增加 `components` / `leveraged_authorizations` / `inventory_items`（或拆 v3 path 抽單獨 `_apply_v2_bundle_overrides` 接 docx 端 Bug C 同 pattern）
4. 對齊 docx 端 preview UI — Phase 4.4 spec 講 generalize 兩端共用

### L6 — i18n keys 規範

`SspComponentsLeveragedInventoryTab.vue` 目前 i18n keys 走 `?? '中文 fallback'`。要在 `src/config/locales/i18n/zh-tw/grc-shared.json` + `en/grc-shared.json` 加 namespace `ssp_components_leveraged_inventory.*`。

### L7 — Phase 1+2 Bug B 仍未查（handoff `2026-05-25-phase1-phase2-FINAL-SUMMARY.md` §8 L2）

docx import 5 parties 全 decision=skip → 0 parties 寫入。FE diff stepper 預設 decision UX 跟 BE 收 payload 對應不明。Phase 4 FE 改 stepper UX 時順手釐清。

### L8 — L1 jedi-oscal 進版 + Nexus push + 主專案 pin 還原（user 拍板才做）

per Phase 1+2 SUMMARY §7.1。Phase 5 已 defer 但 Phase 3+4 ship 完仍要 bump 套件版本（套件 layer 沒改但主專案使用方式有改）。**user 2026-05-25 拍板「進版不用做，等測完才會說」** — 等 user。

### L9 — BE/FE 版號 1:1 對齊（v1.1.0 → v1.2.0？）

per memory `feedback_be_fe_version_alignment`。整個 feature 收尾後同步 bump，user 拍板進版時做。

---

## 6. 部署 handover（user 拍板才執行）

### 6.1 部署順序

1. jedi-oscal（套件本身沒改但對應 caller 改了 → 不需 bump，pin 不變）
2. 主專案 deploy（含 Phase 3.1 v3.0.0 sheet 重組）
3. FE 同步 deploy（新 tab + Phase 4 完工部分）
4. **重要**：user 必須先「下載 v3.0.0 樣板」再上傳；現有 v2.x 樣板會被 reject

### 6.2 BE 重啟必做

per `feedback_be_restart_after_service_change`：

- 改了 `app/oscal/service/excel_parser/*.py`（4 個檔）
- 改了 `app/oscal/service/ssp_components_app_service.py` / `ssp_inventory_items_app_service.py`
- 改了 `app/module_frame/excel_template/sheet_definitions.py` / `generator.py`
- 改了 `app/module_frame/service/ssp_import_template_app_service.py`
- 改了 `domain/oscal/parser/docx_section_extractors.py` / `domain/oscal/adapter/cmmc_ssp_adapter.py`

`kill -9 <pid>` 後 restart（per `feedback_backend_restart_orphan_pids`）。

### 6.3 兩 repo `git push`

兩 repo 都還 local（主專案 28 commits ahead / FE 1 commit ahead）。Push 需 user 明確指示。

---

## 7. 給下個 session 接手的精簡開工 prompt（直接複製貼）

```
你接手 SSP OSCAL Alignment Phase 4 收尾。Phase 3 全完工（§3.1 v3.0.0 sheet 重組 +
§3.2 docx extractors + §3.3 reference regen），Phase 4 部分完工（BE read endpoints +
FE 新 tab read-only display + BE write endpoints WIP）。Phase 5 已 defer。

按以下順序讀文件（共 5 個）：
1. docs/features/FR-028-2605-ssp-oscal-alignment/handoff/2026-05-25-phase3-DONE-phase4-WIP-SUMMARY.md
   （本 SUMMARY — 整個本期完工 + 未完項目）
2. docs/features/FR-028-2605-ssp-oscal-alignment/design.md §3 + §4（Phase 3 + Phase 4 spec；§5 已 defer 可跳）
3. docs/features/FR-028-2605-ssp-oscal-alignment/handoff/2026-05-25-phase1-phase2-FINAL-SUMMARY.md
   §8 L1/L2/L3（Bug A/B/C + 進版 leftover）
4. app/oscal/service/ssp_components_app_service.py（WIP CRUD 已加，看 pattern）
5. FE 端必讀：~/Projects/Billows/Audit-Manager/compliance-manager-fe/CLAUDE.md
   （per memory feedback_cross_repo_read_claude_md_first — 跨 repo 動工必讀）

開工順位（per 本 SUMMARY §5 L1~L9）：
- **緊迫**：L5 Phase 4.4 FE Excel preview 對齊 v3 keys（Phase 3.1 ship 後 preview 空）
- 必收：L1 BE write endpoints route + inventory CRUD → L2 FE inline CRUD → L3 移除舊 tabs
- 完整度：L4 5-tab 結構 → L6 i18n 規範
- 排查：L7 Bug B / L8 進版 / L9 BE/FE 版號對齊

開工前 pre-flight：
- git branch --show-current → feature/ssp-oscal-alignment（兩 repo 一致）
- git status: M pyproject.toml only（dev-only path-dep，**永不 stage**）
- BE test smoke：poetry run pytest tests/test_excel_parser_v2_bundle.py
  tests/test_excel_parser.py tests/test_ssp_import_pipeline_smoke.py
  tests/test_cmmc_ssp_adapter_v3_bundle.py — 全綠
- FE test smoke：cd ~/Projects/Billows/Audit-Manager/compliance-manager-fe && npx vite build → 通

收尾後（user 拍板才做）：jedi-oscal 進版（如有改套件）+ 兩 repo git push + BE/FE
版號對齊 bump（per memory feedback_be_fe_version_alignment）。
```

---

## 附錄 A — 路徑速查

| 用途 | 路徑 |
|---|---|
| 本 SUMMARY | `docs/features/FR-028-2605-ssp-oscal-alignment/handoff/2026-05-25-phase3-DONE-phase4-WIP-SUMMARY.md` |
| Phase 1+2 FINAL SUMMARY | `docs/features/FR-028-2605-ssp-oscal-alignment/handoff/2026-05-25-phase1-phase2-FINAL-SUMMARY.md` |
| Phase 3+4 handoff（原）| `docs/features/FR-028-2605-ssp-oscal-alignment/handoff/2026-05-25-phase3-4-handoff.md` |
| design.md v1.2 + §11 reconciliation 17 條 + §5 defer banner | `docs/features/FR-028-2605-ssp-oscal-alignment/design.md` |
| Excel sheet defs v3.0.0 | `app/module_frame/excel_template/sheet_definitions.py` |
| Excel parser | `app/oscal/service/excel_parser/{parser,sheet_handlers,types,version_check,v2_bundle}.py` |
| Excel app service | `app/oscal/service/ssp_excel_import_app_service.py` |
| Components / Inventory 新 app services | `app/oscal/service/ssp_components_app_service.py` / `ssp_inventory_items_app_service.py` |
| Docx extractors（新 components / inventory）| `domain/oscal/parser/docx_section_extractors.py` |
| Docx adapter v3 bundle | `domain/oscal/adapter/cmmc_ssp_adapter.py` |
| FE 新 tab | `~/Projects/Billows/Audit-Manager/compliance-manager-fe/src/components/grc/ssp/SspComponentsLeveragedInventoryTab.vue` |
| FE SSP tab root | `~/Projects/Billows/Audit-Manager/compliance-manager-fe/src/components/grc/ssp/SspTabPanel.vue` |
| FE Excel preview（**待 §3.1 對齊**）| `~/Projects/Billows/Audit-Manager/compliance-manager-fe/src/components/grc/ssp-excel-import/SheetPreview*.vue` |
| Reference templates v3.0.0 | `docs/features/FR-011.2-2605-ssp-import-export-phase2/reference/ssp_template_*_v3.0.0.xlsx` |