# FR-032 Phase E-a 收尾 SUMMARY — Excel round-trip

| 項目 | 內容 |
|------|------|
| 階段 | FR-032 Phase E-a（Excel 匯入回灌 + 設備/系統資產 picker round-trip）|
| 日期 | 2026-06-04 |
| Branch | `feature/FR-032`（BE / FE 各自）|
| 狀態 | ✅ 完成、已驗證、**未 push** |
| 測試 | FR-032 全套 **67 綠**；匯入管線回歸 99 綠；零新增 regression |

---

## 1. 做了什麼（行為差異）

E-a 把 Excel 匯入管線從「只懂設備」擴成「設備 + 系統資產雙資產類別 + 雙向鉤稽」：

1. **系統資產匯入回灌** — Excel 新增「系統資產」sheet，匯入時依**系統名稱**比對
   `compliance.information_systems` master：配到自動鉤稽（設 `ref_id` + 用 master snapshot
   回填 props）；配不到自由輸入新建。落點是共用 inventory 表 `asset_type='information_system'` 列。
2. **「資產」→「設備資產」改名** + 第一欄 header「描述」→「名稱」（對齊 docx 與 FE live 表）。
3. **兩 sheet 都加 picker（比照參與人員）**：
   - 設備資產：`鉤稽設備` 下拉挑既有設備 → autofill 名稱/IP/OS → 匯入鉤稽 jedi-device（`ref_type='device'`，merge 設備欄位）。
   - 系統資產：`鉤稽系統` 下拉挑既有資訊系統 → autofill 6 欄 → 匯入仍依 name 比對 master 鉤稽。
4. **下載填值 round-trip 雙向回填** — 下載已鉤稽資產的填值樣板時，把 picker 回填成下拉 label
   （設備 `name (ip)` / 系統 `abbr - name`），下載 → picker 顯示已選 → re-upload 可重新鉤稽。
5. **修復**：資源庫範本下載填值原本「資產」+「系統資產」都空白（MF-scoped 下載路徑寫死
   `inventory_items=[]` 的舊缺口 + 未注入 MF inventory default service）→ 補齊。

樣板版本 `TEMPLATE_VERSION` v3.0.6 → **v3.3.0**（舊 v3.0–v3.2 樣板靠 legacy alias + 尾端
picker 欄 backward-compat 仍可上傳）。

---

## 2. Commits（皆未 push）

### BE（`feature/FR-032`，compliance-manager-be）
```
22929d6e feat(FR-032 E-a 後續): 系統資產 sheet 加資訊系統 picker + 設備/系統資產下載回填
9116e5df feat(FR-032 E-a 後續): Excel「資產」改名「設備資產」+ 設備 picker 完整 round-trip（BE）
e51bd809 fix(FR-032 E-a): 範本 template-edit 下載填值補上資產 + 系統資產（round-trip）
743fc2a3 feat(FR-032 E-a): 系統資產匯入預覽支援（preview 比對標記 + override/removal wiring）
1359ce48 feat(FR-032 E-a): Excel 匯入回灌系統資產 + 依名稱比對 information_systems master（BE）
```

### FE（`feature/FR-032`，compliance-manager-fe）
```
f983e38 feat(FR-032 E-a 後續): 匯入預覽「設備資產」文案 + 設備鉤稽欄（FE）
8c888e2 feat(FR-032 E-a): Excel 匯入預覽加「系統資產」sheet（FE Layer 5）
```

### jedi 套件
本期**未動 jedi 套件**（`InventoryItemEntity` 的 asset_type/ref 欄位 F 期已落地）。
`pyproject.toml` 的 jedi-device path 是 dev-only，**故意未 commit**。

---

## 3. 改動範圍（主要檔案）

**BE**
- 樣板：`app/module_frame/excel_template/{sheet_definitions,header_i18n,generator}.py`
- parser：`app/oscal/service/excel_parser/{sheet_handlers,parser,types,v2_bundle}.py`
- 中間表示 / pipeline：`domain/oscal/parser/ssp_intermediate.py`、
  `domain/oscal/import_pipeline/{bundle_restore,normalizer,confirm_service}.py`
- 共用：`common/util/system_asset_snapshot.py`（`resolve_system_asset_fields` /
  `resolve_device_inventory_fields`）
- 寫入 / preview：`app/oscal/service/ssp_excel_import_app_service.py`、
  `domain/oscal/service/write_strategy/inventory_item_write_strategy.py`
- 下載 / 回填：`app/module_frame/service/ssp_import_template_app_service.py`
- DI：`di_containers/oscal/oscal_containers.py`、`di_containers/module_frame/module_frame_containers.py`
- 測試：`test/test_fr032_excel_system_assets.py`（44）、`test/test_fr032_excel_device_roundtrip.py`（13）

**FE**
- `src/components/grc/ssp-excel-import/SheetPreviewSystemAssets.vue`（新）、`SheetPreviewInventoryItems.vue`
- `src/views/module_frame/ImportExcelPreviewPage.vue`、`src/stores/sspExcelImportStore.js`
- i18n：`src/config/locales/i18n/{en,zh-tw}/ssp-excel-import.json`

---

## 4. 規範文件（✓ 已更新 / 留 follow-up）

- ✓ changelog：`docs/changelog/2026-06-04-feat-fr032-ea-excel-roundtrip.md`
- ✓ design.md §11.11~11.19（E-a 偏差紀錄）+ §11 index（E-a → ✅）
- ✓ handoff `2026-06-04-ea-excel-roundtrip-handoff.md` 加 `✅ DONE` 標頭
- ✓ 本 SUMMARY
- ✓ memory feedback（Excel autofill calc-mode / MF vs SSP 下載路徑分流）+ MEMORY.md 索引
- ✗（留 follow-up）：api-spec.md / frontend-overview.md — Excel 匯入模組無獨立 api-spec；
  preview 元件屬內部 FE，未動 BE 視角速查文件

---

## 5. 已知限制 / follow-up

| 項目 | 說明 |
|------|------|
| Excel autofill 依 client 計算模式 | MS Excel「手動重算」模式挑下拉不即時帶入；公式經 LibreOffice recalc 驗證正確（非 bug）。不影響匯入（BE 從 master 填欄位）。可於「說明」分頁加重算提示 |
| E-b（docx 匯入回灌系統資產）| 走 per-framework adapter，獨立階段 |
| OSCAL-native 匯出 / docx components-leveraged repoint / G | 同 A-F 期 follow-up |
| 既有 `tests/test_excel_*` stale 測試 | v3 改版後未同步斷言的一批失敗，與本期無關，未動；可另開一輪清理 |

---

## 6. 部署 handover

- **改了 BE service + DI**：部署 / 本機驗證前需**重啟 BE**（無 hot reload）。
- **新樣板 v3.3.0**：使用者需下載新樣板才看得到 picker 欄；舊樣板仍可上傳（backward-compat）。
- DB 無新 migration（沿用 A-F 期 `asset_type/ref_type/ref_id` 欄位）。
- push：BE / FE 各自 branch，**等 user 明示**。