# SSP OSCAL Alignment — Phase 4 COMPLETE SUMMARY — 2026-05-25

| 項目 | 內容 |
|---|---|
| Phase 範圍 | **Phase 4 主要工作全完工**（L5 緊迫 / L1a 必收 / L2 必收 / L3 必收 / L6 完整度）+ **L4 skip**（spec under-defined + user 拍板）+ **L7/L8/L9 等 user 拍板** |
| 日期區間 | 2026-05-25（單日全程） |
| Branch（兩 repo 一致）| `feature/ssp-oscal-alignment` |
| 主專案 local commits | **33**（baseline `d12bd705` Phase 1+2 收尾後；本期 +5 commits）|
| 主專案 working tree | `M pyproject.toml`（path-dep dev-only，**永遠不 stage**）|
| FE local commits | **5**（baseline `e873fae`；本期 +3 commits）|
| FE working tree | clean |
| Test 狀態 | BE pytest smoke 106 passed / FE vite build ✓ in 7.04s |
| 下一步 | **本期主軸 ship 完，user 重啟 BE + manual 測試** → user 拍板進版 (L8 jedi-oscal bump + L9 BE/FE 版號對齊) → 部署 staging / prod |

---

## 0. 一句話收尾

**Phase 4 demo gap 全收尾**：FE v3 樣板上傳 preview 不再空（L5）+ SSP 編輯第四 tab 可 inline CRUD（L2）+ BE write endpoints 對外暴露（L1a）+ 舊 3 tab 從 SSP edit 移除（L3）+ i18n keys 從 fallback 移到正規 namespace（L6）。L4 5-tab 結構因 spec under-defined + user 拍板「控制項本來就沒有」維持現狀 4 tab。

---

## 1. 本期 commits 清單（共 5 commits 跨兩 repo）

### FE（3 commits，baseline `bd23047`）

| Commit | Task | 摘要 |
|---|---|---|
| `bfab64b` | L5 | feat: v3-bundle Excel preview elements（新建 3 SheetPreview + wrapper 切換 + store REMOVED_KEYS + i18n keys） |
| `00c2587` | L2+L3 | feat: inline CRUD on 第四 tab + 移除舊 3 tab（SspService 6 method + SspComponentsLeveragedInventoryTab 加 3 Dialog + SspTabPanel 4 tab + 移除舊 import） |
| `05b6fdf` | L6 | feat: i18n keys 從 fallback 移到正規 namespace（新 `ssp-components-leveraged-inventory.json` zh-tw+en + index.js 註冊 + common.json `action` + vue 檔 69/71 fallback 移除） |

### BE（2 commits，baseline `c3c94473`）

| Commit | Task | 摘要 |
|---|---|---|
| `eedad8ab` | L5 BE | feat: `_ROW_OVERRIDE_SHEETS` 接 v3 keys（components / leveraged_authorizations / inventory_items；保留舊 v1 keys 兼容） |
| `b02f833e` | L1a | feat: Components / Inventory write endpoints CRUD（components route 加 post + DetailResource；inventory app service 補 add/update/delete_item；M2M no-op 加 warning；api/oscal/__init__.py 兩條 detail route） |

**Memory 更新**：無新增（本期沒新行為規範可記入）。

---

## 2. Phase 4 task 完工 / skip / TODO 一覽

| Task | Status | 內容 |
|---|---|---|
| L5 緊迫 — FE Excel preview 對齊 v3 keys | ✅ DONE | 3 個新 SheetPreview 元件 + wrapper 切換 + BE override sheets 加 v3 keys |
| L1a 必收 — BE Components/Inventory write endpoints + inventory app service CRUD | ✅ DONE | route post + DetailResource × 2 + inventory app service add/update/delete + M2M silent skip pattern |
| L2 必收 — FE inline CRUD on 第四 tab | ✅ DONE | 3 個 Add/Edit Dialog × 3 entity + per-row Edit/Delete + add button × 3 section + SspService 6 method |
| L3 必收 — 移除舊 3 tab + 廢棄 vue 元件 | ✅ DONE 部分 | SspTabPanel 移除 tab 5/6/7 + import / counts / SECTION_TAB_MAP redirect。**舊 vue 元件保留**（MF /template-edit 還用 apiBase='module-frame'）|
| L4 完整度 — Phase 4.1 5-tab 完整結構 | ⏭ **SKIP** | 3 個 sub-item 全 skip（SC 拆 / parties 合併 / 控制項 tab）— spec under-defined + user 拍板「控制項本來 SSP 編輯就沒有」 |
| L6 完整度 — i18n keys 從 fallback 移到正規 namespace | ✅ DONE | 新 namespace JSON 雙語 + index.js 註冊 + common.json 補 `action` + vue 檔 69/71 fallback 移除（剩 2 處非 i18n 用途 fallback 保留） |
| L7 排查 — Bug B docx parties 全 skip | ⏸ **未開工** | Phase 1+2 SUMMARY §8 L2 留下；推測 FE diff stepper 預設 decision=skip 而非 accept；Phase 5+ FE 改 stepper UX 時順手釐清 |
| L8 — jedi-oscal 進版 + Nexus push + 主專案 pin 還原 | ⏸ **等 user 拍板** | user 2026-05-25 拍板「進版不用做，等測完才會說」 |
| L9 — BE/FE 版號 1:1 對齊（v1.1.0 → v1.2.0?） | ⏸ **等 user 拍板** | per memory `feedback_be_fe_version_alignment`；user 拍板進版時做 |

---

## 3. 行為差異對使用者影響

### 3.1 Excel 上傳 preview 不再空（L5）

- v3.0.0 樣板上傳後進入 preview，「元件清冊 / 利用授權 / 資產清冊」三 tab 顯示完整內容（不再空白）
- v1.x in-flight parse_jobs 也走 v3 preview（v2_bundle.py 對 v1 樣板 derive v3 keys）
- 「devices / info_systems / leveraged」舊 tab 從 preview wrapper 消失

### 3.2 SSP 編輯第四 tab 可 inline CRUD（L2）

- 「元件 + 授權 + 資產」整合 tab 加 3 個 Add/Edit Dialog + per-row Edit/Delete + 新增 Button
- Component dialog 9 fields（含 14 OSCAL component_type enum + 5 status enum + leveraged_authorization Dropdown）
- LeveragedAuth dialog 8 fields（含 date_authorized Calendar + 4 category enum）
- Inventory dialog 10 fields（含 implemented_components MultiSelect chip picker；Edit mode 對 M2M field disabled + hint）

### 3.3 SSP 編輯舊 3 tab 全消失（L3）

- 「設備（舊）/ 資訊系統（舊）/ 外部利用服務（舊）」3 tab 從 SspTabPanel 移除
- 舊 deep-link query string (`?section=scope_devices` etc.) **仍可用** — redirect 到整合 tab (index 3) 保留書籤兼容
- MF /template-edit 仍用舊三檔 vue 元件（apiBase='module-frame'），不受影響

### 3.4 BE 新 endpoints（L1a）

| URL | Methods |
|---|---|
| `/ssp/<uid>/components` | GET / POST |
| `/ssp/<uid>/components/<item_uid>` | PUT / DELETE |
| `/ssp/<uid>/inventory-items` | GET / POST |
| `/ssp/<uid>/inventory-items/<item_uid>` | PUT / DELETE |

- `inventory.update_item` 對 M2M (`implemented_component_uids`) silent skip + log warning（per entity §Mutation contract — 改 M2M 必須 delete + recreate）

### 3.5 i18n keys cleanup（L6）

- 新 `lang.ssp_components_leveraged_inventory.*` namespace（zh-tw + en），約 30 key
- `lang.common.action` 補進 common.json（兩 locale）
- vue 檔 missing key 不再依賴 fallback —— missing key 走 vue-i18n fallbackLocale='en' 接住 + console warning

---

## 4. 規範文件齊全度

| 項目 | 路徑 | 狀態 |
|---|---|---|
| design.md §11 補本期 reconciliation（§11.18 ~ §11.21）| `docs/features/FR-028-2605-ssp-oscal-alignment/design.md` | ✅ 本 commit batch（4 條 entries） |
| 本 SUMMARY | `docs/features/FR-028-2605-ssp-oscal-alignment/handoff/2026-05-25-phase4-COMPLETE-SUMMARY.md` | ✅ 本文件 |
| Changelog batch | `docs/changelog/2026-05-25-feat-ssp-oscal-alignment-phase4.md` | ❌ 後續 commit 補 |
| Conversation history JSONL extract | `docs/conversation-history/2026-05-25/ssp-oscal-alignment-phase3-4/` | ❌ session 結束後 extract |

---

## 5. 已知 follow-ups

### L4 5-tab 結構 sub-item 全 skip — 未來 phase 才做

per §11.20，三個 sub-item 都需要 spec 先補才能 execute：
1. SC 拆 (從 SspBasicSection 拆出獨立 tab) — 需 user 對 UX 對齊「拆」的具體意思
2. 單位 + 參與人員合併 — 需 UX 設計（兩 party_type 在一個 panel 怎麼 filter / switch）
3. 控制項 tab — user 拍板維持「沒有」（TaskSetupView 是控制項編輯主場）

→ L4 不在 Phase 4 收尾 scope；維持現狀 4-tab。

### L7 Bug B docx parties 全 skip — ⚠️ **更新 2026-05-25 收尾後** — 改為**現在優先 fix**

**前期 (Phase 1+2 SUMMARY §8 L2) 描述過時** — 寫「Phase 5+ FE 改 stepper UX 時順手釐清」+「BE 不主動改」。

**實際情況**：
- 本 session user 做 Phase 4 ship 後手動 docx 驗證即踩到，**每次 import 都中** — 不能等 Phase 5+
- BE log 已 confirmed root cause 在 FE diff stepper 預設值（不是「推測」）
- L4 5-tab 全 skip 連帶 L7 也沒在 Phase 4 處理 — handoff 給下個 session

**接手 session 看這份**：`docs/features/FR-028-2605-ssp-oscal-alignment/handoff/2026-05-25-bug-b-and-parties-stepper-handoff.md`（完整 diagnosis + fix plan A/B + verify checklist）

**優先度**：**最高** — 跟 Issue 1（parties preview 缺電話/職稱/地址欄位）同 stepper component 一起 fix。

### L8 jedi-oscal 進版 — 等 user 拍板

per Phase 1+2 SUMMARY §7.1（user 2026-05-25 拍板「進版不用做，等測完才會說」）。
執行步驟見該 SUMMARY §7.1。

### L9 BE/FE 版號 1:1 對齊 — 等 user 拍板

per memory `feedback_be_fe_version_alignment`。Phase 4 完工後同 L8 一起 bump。
建議版號：`v1.1.0 → v1.2.0`（Phase 3+4 含 v3.0.0 Excel BREAKING + Phase 4 新 UX，functional 範圍夠 functional bump；不是 major bump 因為對外 API 沒 breaking — `/ssp/<uid>/components` 等新 endpoint 是 additive）。

### 3 個 changelog 應補（user 收尾完手動補或下次 session）

per memory `feedback_changelog_subagent` + CLAUDE.md「收尾才寫 batch」：
1. `docs/changelog/2026-05-25-feat-ssp-oscal-alignment-phase4-l5.md` — FE Excel preview v3 對齊
2. `docs/changelog/2026-05-25-feat-ssp-oscal-alignment-phase4-l1a-l2-l3.md` — BE CRUD endpoints + FE inline CRUD + 移除舊 tab
3. `docs/changelog/2026-05-25-feat-ssp-oscal-alignment-phase4-l6.md` — i18n keys cleanup

或合併成單一 `docs/changelog/2026-05-25-feat-ssp-oscal-alignment-phase4.md` 涵蓋全部。本 SUMMARY 已具備 changelog 等同訊息量，user 可選擇是否另寫 changelog。

---

## 6. 部署 handover

### 6.1 部署順序（user 拍板 push 後）

1. jedi-oscal 進版（若 user 拍板 L8）— 套件本身沒改但 caller 用法有改 → 看 user 拍板「進版 vs 不進版」
2. 主專案 deploy（含 Phase 4 L5 BE `_ROW_OVERRIDE_SHEETS` 擴 + L1a CRUD endpoints + 既有 Phase 3 v3.0.0 樣板）
3. FE 同步 deploy（含 L5 v3 preview + L2 inline CRUD + L3 移除舊 tab + L6 i18n）
4. **重要**：user 必須先「下載 v3.0.0 樣板」再上傳 — 現有 v2.x 樣板會被 parser reject（per Phase 3.1 commit `f7eaa09f`）

### 6.2 BE 重啟必做

per memory `feedback_be_restart_after_service_change`：

本期改動的 BE service / route：
- `app/oscal/service/ssp_excel_import_app_service.py` (`_ROW_OVERRIDE_SHEETS`)
- `app/oscal/service/ssp_inventory_items_app_service.py`（新加 add_item / update_item / delete_item / helpers）
- `api/oscal/routes/ssp/ssp_components_route.py`（加 post + DetailResource）
- `api/oscal/routes/ssp/ssp_inventory_items_route.py`（加 post + DetailResource）
- `api/oscal/__init__.py`（add_resource 兩條 detail route）

```bash
# 重啟前 kill 舊 process（per memory feedback_backend_restart_orphan_pids）
lsof -t -i:8000 | xargs -r kill -9
# 重啟（看你跑哪個）
python main_socketio.py  # 或 python main_app.py
```

### 6.3 兩 repo `git push`

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

### 6.4 手動測試 checklist（user 重啟後）

| 測試項 | 預期 |
|---|---|
| 上傳 v3.0.0 樣板 → preview | 「元件清冊 / 利用授權 / 資產清冊」三 tab 各顯示對應資料（不再空白） |
| 上傳 v1.x 樣板 | parser reject (GRC_EXCEL_TEMPLATE_VERSION_UNSUPPORTED) 提示重下新樣板 |
| SSP 編輯第四 tab → 點「新增元件」 | Dialog 開啟，9 fields 可填，存檔後新 row 出現 |
| SSP 編輯第四 tab → row 點「編輯」 | Dialog 開啟，欄位預填，存檔後 row 更新 |
| SSP 編輯第四 tab → row 點「刪除」 | ConfirmDialog 開啟，確認後 row 消失 |
| inventory 編輯 → implemented_components MultiSelect | 顯示 disabled + hint「（編輯模式下不可變更 — 需刪除後重建）」|
| SSP 編輯 → tab 列只有 4 tab | 「設備（舊）/ 資訊系統（舊）/ 外部利用服務（舊）」三 tab 消失 |
| 舊書籤 `?section=scope_devices` | 自動 redirect 到「元件 + 授權 + 資產」整合 tab |
| MF /template-edit | 舊 SspLeveragedSection / ModuleFrameSspDevicesPanel / ModuleFrameSspInfoSystemsPanel 仍可正常編輯（apiBase='module-frame'）|

---

## 7. 給下個 session 的精簡 prompt

```
SSP OSCAL Alignment Phase 4 已完工（L5/L1a/L2/L3/L6 done；L4 skip；L7/L8/L9 等
user 拍板）。本期 5 commits 跨兩 repo（FE 3 + BE 2）。詳見：
docs/features/FR-028-2605-ssp-oscal-alignment/handoff/2026-05-25-phase4-COMPLETE-SUMMARY.md

下個 session 可能要做（按優先順序）：
1. user 拍板進版 → L8 (jedi-oscal bump + Nexus push + 主專案 pin 還原) + L9
   (BE/FE 版號對齊 v1.1.0 → v1.2.0?)
2. L7 排查 Bug B (docx parties 全 skip) — Phase 5+ FE 改 stepper UX 時順手做
3. L4 5-tab 結構 (SC 拆 / parties 合併) — 需先補 UX spec 才能 execute
4. Phase 5 OSCAL Export — 整個 feature 收尾 (round-trip e2e)

開工前 pre-flight：
- git branch --show-current → feature/ssp-oscal-alignment（兩 repo 一致）
- BE working tree: M pyproject.toml only (dev-only path-dep)
- BE test smoke：poetry run pytest tests/test_excel_parser_v2_bundle.py
  tests/test_ssp_excel_import_app_service.py — 106 passed
- FE build smoke：cd ~/Projects/Billows/Audit-Manager/compliance-manager-fe
  && npx vite build → 通
```

---

## 附錄 A — 路徑速查

| 用途 | 路徑 |
|---|---|
| 本 SUMMARY | `docs/features/FR-028-2605-ssp-oscal-alignment/handoff/2026-05-25-phase4-COMPLETE-SUMMARY.md` |
| Phase 3 + 4 WIP SUMMARY（前接 handoff）| `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` |
| design.md（§11.18 ~ §11.21 本期新增）| `docs/features/FR-028-2605-ssp-oscal-alignment/design.md` |
| BE Components / Inventory app service | `app/oscal/service/ssp_components_app_service.py` / `ssp_inventory_items_app_service.py` |
| BE Components / Inventory route | `api/oscal/routes/ssp/ssp_components_route.py` / `ssp_inventory_items_route.py` |
| BE Excel `_ROW_OVERRIDE_SHEETS` | `app/oscal/service/ssp_excel_import_app_service.py:1259` |
| FE 第四 tab inline CRUD | `~/Projects/Billows/Audit-Manager/compliance-manager-fe/src/components/grc/ssp/SspComponentsLeveragedInventoryTab.vue` |
| FE 第四 tab caller (SspTabPanel)| `~/Projects/Billows/Audit-Manager/compliance-manager-fe/src/components/grc/ssp/SspTabPanel.vue` |
| FE v3 preview 三檔 | `~/Projects/Billows/Audit-Manager/compliance-manager-fe/src/components/grc/ssp-excel-import/SheetPreview{Components,LeveragedAuth,InventoryItems}.vue` |
| FE wrapper | `~/Projects/Billows/Audit-Manager/compliance-manager-fe/src/views/module_frame/ImportExcelPreviewPage.vue` |
| FE SspService | `~/Projects/Billows/Audit-Manager/compliance-manager-fe/src/service/SspService.js` |
| FE i18n namespace（zh-tw + en）| `~/Projects/Billows/Audit-Manager/compliance-manager-fe/src/config/locales/i18n/{zh-tw,en}/ssp-components-leveraged-inventory.json` |