# Bugfix Phase Final SUMMARY — A5 smoke 後 bugfix + UX 重構

> **時程**：2026-05-21（單一長 session）
> **狀態**：所有 commits ✅；user 驗收進行中（單位 panel spinner fix 待測）
> **跨 repo**：compliance-manager-be + compliance-manager-fe + jedi-oscal（dev path dep，未發版）

---

## 1. 這段時間在幹嘛（一句話）

從 A5 smoke 收到 user bug report，連環修補 → 順勢做 template-edit 大幅 UX 重構（Phase 1 / 2 / 2.4 / 3）→ 整理 loading 規範 → perf 優化（N+1 + composable cache）→ 4 panel UI 統一。

---

## 2. 工作流程脈絡

| 階段 | 觸發 | 結果 |
|------|------|------|
| **Stage 1 — Excel 匯入 bugfix** | A5 smoke checklist 後 user 報「實施狀態 / 現況說明 / parties role / 設備/資訊系統無法維護」3 issue | Issue 1 / 2 / 3 三組 commit |
| **Stage 2 — Excel 樣板強化** | User 反饋 02_單位 沒下拉、欄位語意不清 | matched_org_unit 下拉 + Excel header cell comment 提示 |
| **Stage 3 — AO 修補** | User 反饋「AO 實施狀態 / 現況說明 沒帶入」 | statement_identifier `(a)/(b)` letter key 對齊 docx + FE |
| **Stage 4 — UX 重構 (Phase 1+2+2.4)** | User 反饋「單位/人員 應分開」+「編輯 menu 太多項目難維護」 | template-edit 主頁變 TabView：基本資料 / 適用控制項 / 單位 / 人員 / 設備 / 資訊系統 / 程序書文件池 |
| **Stage 5 — 規範強化** | User 反饋「資料載入要有 loading」 | FE CLAUDE.md「Loading 規範」⭐ 必讀 + LoadingState 共用元件 |
| **Stage 6 — Perf 優化** | User 反饋「單位/人員 讀取慢」 | FE composable cache（兩 panel 共用 fetch）+ BE batch fetch（消 N+1）|
| **Stage 7 — UI 統一** | User 反饋「4 個 panel UI 不一致」 | 全部改 DataTable + 同 column pattern + 同 empty / loading 樣式 |

---

## 3. Commit 清單

### BE repo (`feature/ssp-import-export-phase2`, 13 commits ahead origin)

```
ca8842b perf(module-frame): list_parties 改 batch fetch，消 N+1 query
d7a850d feat(module-frame): SSP info_systems 也帶 matched picker FK 出來
127c2fe feat(module-frame): 新增 SSP 資源 CRUD endpoints (devices / info_systems)
b8c3f69 fix(ssp-excel-import): AO statement_identifier 用 (a)/(b) letter key
d8cf8a4 tweak(ssp-excel-import): 07_控制項與AO header 不加 cell comment
d0b1657 tweak(ssp-excel-import): Excel 樣板下拉欄 header 加 cell comment
8270dad feat(ssp-excel-import): 02_單位 sheet 加 matched_org_unit 下拉
95df3b3 feat(module-frame): 新增 /module-frame/<uid>/ssp-resources GET API
f454fe7 fix(ssp-excel-import): org party 預設 role fallback responsible-organization
ece9a1d fix(ssp-excel-import): confirm 加寫 MF defaults，template-edit 才看得到資料
```

> 加 A5 smoke 後的早期 bugfix（`ce00996` / `9e1c201` / `38f31aa` 等），共 13 commits。

### FE repo (`feature/ssp-import-export-phase2`, 15 commits ahead origin)

```
926dd34 tweak(module-frame): 4 個 entity panel UI 統一 DataTable + 同 column pattern
16eb34d fix(module-frame): 修單位 panel 一直轉圈圈 — 拔 immediate watch + cache 永久化
d7a52ef perf(module-frame): 單位 / 人員 panel 共用 fetch (composable cache)
6ad438f tweak(module-frame): 統一 loading 風格 + 下載 SSP 樣板 → Excel 樣板
f84511e tweak(module-frame): 批次維護 menu 重新分組 + 砍下載空白樣板
05c814b tweak(module-frame): template-edit 加頁面層級 loading + 強化 FE CLAUDE.md loading 規範
1475fe2 feat(module-frame): 設備 / 資訊系統 panel 加 inline CRUD + picker 連動
be660a3 tweak(i18n): 編輯現況與程序書 → 編輯合規資源庫
1e8413d tweak(module-frame): template-edit tab name 微調
ef79817 tweak(module-frame): 基本資料成 Tab 0；編輯適用控制項挪進控制項 tab；edit menu 移除
7b06887 tweak(module-frame): template-edit 主頁加 TabView，6 entity 攤平 (Phase 2 of B)
66e477f tweak(module-frame): template-edit dialog 內邏輯抽成 panel (Phase 1 of B TabView)
ed0c55f feat(module-frame): template-edit 加「SSP 設備 / 資訊系統」dialog
d7dbf1c fix(module-frame): 參與人員 dialog ROLE_LABEL 加 ParticipantRole 對應
7ef3b74 fix(ssp-excel-import): confirm 成功後 redirect 改 module-frame-template-edit
```

### jedi-oscal（path dep dev mode，尚未發版）

- `oscal_party_query_entity.py` 加 `_in_uid` 欄位（給 BE batch fetch 用）

---

## 4. 變更紀錄文件齊全度

### BE changelog (`docs/changelog/2026-05-21-*.md`) — 18 份

涵蓋 Stage 1~6 + A5 smoke 早期 bugfix。**齊全**。

### FE changelog (`docs/changelog/2026-05-21-*.md`) — 20 份

涵蓋 Stage 1~7。**齊全**。

### Issue 文件

本期均為「root cause 顯而易見」型 bug，未開 `docs/issues/`（符合 CLAUDE.md「未來踩同一坑 dev 想看完整 root cause」判斷準則 — 大部分 fix 在 changelog 已完整說明）。

---

## 5. 架構性改動 summary

### template-edit 主頁從 dropdown menu 改 TabView

```
Before                          After
[編輯 ▾] dropdown 內 5 項        [TabView] 7 tabs:
  ├ 編輯基本資料                  ├ 基本資料 (Tab 0)
  ├ 編輯適用控制項                ├ 適用控制項
  ├ 參與人員 (單位+人員混)        ├ 單位 (N) [按 count badge]
  ├ SSP 設備/資訊系統             ├ 人員 (M)
  └ 程序書文件池                  ├ 設備 (X)
                                  ├ 資訊系統 (Y)
                                  └ 程序書文件池

「編輯適用控制項」變成「適用控制項」tab 內 button（跟 tree 內容 1:1 連動）
```

### 6 個新 panel component（從 dialog 抽出可獨立掛載）

| Component | 用途 |
|-----------|------|
| `ModuleFramePartiesPanel` | 單位 / 人員 共用，`partyType` prop 控制 |
| `ModuleFrameSspDevicesPanel` | 設備 CRUD + picker |
| `ModuleFrameSspInfoSystemsPanel` | 資訊系統 CRUD + picker |
| `ModuleFrameBasicInfoPanel` | MF 基本資料 form |
| `LoadingState` (共用) | 統一 loading 視覺（page / panel / inline 三尺寸） |

### BE 新 API

| Endpoint | 用途 |
|----------|------|
| GET `/module-frame/<uid>/ssp-resources` | 列 SSP 層 devices + info_systems |
| POST `/module-frame/<uid>/ssp-resources/items` | 新增 |
| PUT `/module-frame/<uid>/ssp-resources/items/<item_uid>` | 編輯 |
| DELETE `/module-frame/<uid>/ssp-resources/items/<item_uid>` | 刪除 |

### Perf 改善（10 個 party 場景）

| 階段 | Before | After |
|------|--------|-------|
| FE API 次數 | 2× (兩 panel 各打) | 1× (composable cache) |
| BE 每次 SQL | 13 (N+1 + 2 enrich) | 4 (batch IN) |
| **總 SQL** | **26** | **4** (~85% 減) |

---

## 6. 已知 follow-up / 待驗收事項

### 未驗收（user 驗收清單）

- [ ] **單位 panel 轉圈圈 bug 是否真的修好**（`16eb34d` 用 onMounted + cache 永久化）— 需強制 refresh 瀏覽器測
- [ ] BE 重啟後 `list_parties` batch fetch 行為正常（10 個 party 場景）
- [ ] 4 panel UI 統一視覺驗收
- [ ] AO `(a)/(b)` letter key 在 template-edit 真的顯示出 Excel 填的內容
- [ ] 設備 / 資訊系統 inline CRUD + picker 連動驗收
- [ ] Tab badge count 即時更新（新增 / 刪除後）

### 已知 incomplete

1. **ssp-resources composable cache 沒做**：設備 + 資訊系統 panel 兩個還是各打一次 `/ssp-resources`（user 中斷，當下 priority 是修轉圈圈 bug）
2. **jedi-oscal 未發版**：path dep dev mode；正式發版要等整個 phase 完成 + user 明確指示
3. **dead code 未清**：`partiesDialogOpen` / `sspResourcesDialogOpen` / `basicEditOpen` / `editMenuRef` / `editMenuItems` 等 ref + 對應 imports 留作 backward compat（不影響功能，下個 phase 可清）

### 預期 pre-existing 失敗測試（與本期工作無關）

- `tests/test_module_frame_write_strategy_v2_parties.py::test_write_parties_refreshes_existing_party_in_place`
- `tests/test_ssp_docx_import_diff_response.py::test_get_parse_result_party_added_when_ssp_has_no_parties`
- `tests/test_flow_engine_workflow.py::TestWorkflowExecutionsRoute::test_FE_050_list_with_jwt`
- `tests/cloud_integration/test_google_drive_integration_e2e.py`

---

## 7. ⚠️ 部署 / 驗收提醒

### 必做

1. **重啟 BE process** — 改了 service / DI / 新 route / domain entity，**path dep develop=true 不需 `poetry update`**
2. **重 build FE** — `npm run build:DEV`
3. **瀏覽器 hard refresh** — Ctrl+Shift+R（清舊 bundle cache）

### 不要動

- `pyproject.toml` 內 `jedi-oscal` path dep 行 **保持 dev mode，不 commit**（CLAUDE.md 規範）
- 未追蹤檔案 `docs/features/ssp-import-export-phase2.zip` / reference .xlsx 都不該入版控

### jedi-oscal 發版（user 明確指示後才做）

```
1. jedi-oscal/pyproject.toml bump 0.0.16 → 0.0.17
2. 套件 commit + push + 推 Nexus
3. 主專案 pyproject.toml 改回 pin 0.0.17
4. poetry update jedi-oscal
```

---

## 8. 下個 session 預期工作

User 計畫換新 session 繼續 **debug + 驗收**。

可能要處理：
- 驗收過程中發現的 UI bug（單位 panel spinner 是否真的好了 / TabView 行為 / 鉤稽 picker 連動）
- 補完 ssp-resources composable cache（如果發現設備/資訊系統打多次）
- 補 inline edit 邊角 case（empty state / required validation）
- 必要時 jedi-oscal 發版（看整個 phase 何時關門）

詳見 `docs/features/FR-011.2-2605-ssp-import-export-phase2/handoff/2026-05-21-bugfix-to-next-session.md`（next session prompt）。

---

## 9. 參考資料索引

### 設計文件
- `docs/features/FR-011.2-2605-ssp-import-export-phase2/design-A5.md`（含 §11 reconciliation）
- `docs/features/FR-011.2-2605-ssp-import-export-phase2/implementation-plan-A5.md`

### 對應 changelog（最重要 7 份）
- BE
  - `2026-05-21-fix-excel-import-write-mf-defaults.md`（Issue 1）
  - `2026-05-21-fix-excel-ao-statement-identifier-letter-key.md`（AO 對齊）
  - `2026-05-21-feat-excel-template-org-matched-lookup.md`（02_單位 下拉）
  - `2026-05-21-perf-module-frame-parties-batch-fetch.md`（N+1 fix）
- FE
  - `2026-05-21-tweak-template-edit-main-tabview.md`（Phase 2 攤平）
  - `2026-05-21-feat-ssp-resources-inline-crud.md`（CRUD + picker）
  - `2026-05-21-tweak-template-edit-panels-ui-unified.md`（4 panel 統一）

### FE 規範文件
- `compliance-manager-fe/CLAUDE.md` Line 185+ 「Loading / 等待狀態規範」⭐ 必讀（本期強化）

---

**收尾完成。下個 session 可從「驗收 + debug」入手 — 看 prompt 文件 `2026-05-21-bugfix-to-next-session.md`。**