Excel 匯入匯出對齊 Session Summary

日期： 2026-05-26
Branch： feature/ssp-oscal-alignment
性質： Excel 匯出樣板、匯入預覽、資料寫入路徑全面對齊 web UI

---

BE commits（15 個，9379f2a6→1a79d6e2）

FE commits（4 個）

---

A. Excel 樣板 sheet 名稱 / 欄位名稱不對齊 web

• 原因：v3.0.0 三個新 sheet 的 i18n key 沒補；舊 sheet 名稱未改
• 修法：補 28 個 i18n key，4 個 sheet 改名，12 個欄位對齊 web 文案

B. MF template-edit「系統元件/外部授權」tab 空白

• 原因：FE tab 顯示條件 templateSspExists && templateSspUid，但 Bug T Phase 2 後資料存在 mf-default tables，不走 template SSP path
• 修法：移除 templateSsp gate，直接 mount ModuleFrameComponentsLeveragedInventoryTab

C. Excel filled 匯出 components/LA 空

• 原因：_populate_filled_data 走 _fetch_mf_items_via_ssp（OSCAL SSP tables），但資料在 mf-default tables
• 修法：注入 MF default DS，優先讀 mf-default tables

D. docx import 後 props 欄位（protocol/security_auth 等）空白

• 原因：_run_mf_default_confirm 存 props 時用 comp_dict.get("props") = None（ParsedComponent 沒有 props 欄位）
• 修法：從 parsed dict flat fields 手動打包成 props dict

E. LA/Component API response 欄位不對齊（provider 等空）

• 原因：_to_dict 回 props:{...} 巢狀，FE 讀 data.provider 扁平
• 修法：_to_dict 展開 6 個 LA 欄位到頂層；FE add/update 送扁平欄位 → BE 打包 props

F. Excel export 受評標的空/欄位不對

• 原因：走 OSCAL SSP path，但 SC 在 mf-default；scope_description null 但 description 有資料
• 修法：注入 MfScDefaultDomainService；scope_description fallback to description

G. AO 現況說明/實作狀態空

• 原因：existing_obj_map key 是 (cid, "(a)") 但 lookup 用 (cid, assessment.uid=UUID)
• 修法：從 assessment.description "[a]..." 提取字母 → "(a)"（對齊 FE aoLetterKey()）

H. 控制項全部「未配對」

• 原因：v2-bundle schema 的 _run_preview_reconcile 直接 return，不跑 catalog matching
• 修法：加 _preview_reconcile_controls，用 CatalogControlReconciler 設 matched_catalog_control_id

I. 角色下拉不對齊 web

• 原因：Excel 用 Billows 4 角色（manager/reviewer/auditor/viewer），web 用 OSCAL ssp_party_role
• 修法：Excel enum 改中文 OSCAL 角色；匯入時 reverse mapping 回 OSCAL key；FE 預覽改用 menuStore

J. 啟動專案 components/LA/inventory 重複

• 原因：Excel import 同時寫進 template SSP OSCAL tables（_run_v2_bundle_confirm）+ MF defaults（Step 6c）；啟動專案兩條 clone 路徑都執行
• 修法：確立 MF defaults 為 single source of truth；_setup_ssp_system_implementation 若 MF defaults 有資料則跳過 template SSP clone

K. SSP-scoped Excel 下載 inventory 空

• 原因：_populate_filled_data_for_ssp hardcoded bundle.inventory_items = []（Phase 4 TODO 未完成）
• 修法：注入 InventoryItemDomainService，讀 ssp_inventory_items by ssp_id

---

Single Source of Truth：MF defaults tables

Bug T Phase 2 建立的架構：

• compliance.module_frame_component_defaults — 系統元件
• compliance.module_frame_leveraged_authorization_defaults — 外部授權
• compliance.module_frame_inventory_item_defaults — 資產
• compliance.module_frame_system_characteristic_defaults — 受評標的

template-edit 頁面讀/寫 → MF defaults
啟動專案 Step 7.6 copy() → MF defaults → project SSP OSCAL tables
_setup_ssp_system_implementation Step 3-5 → 有 MF defaults 時 skip template SSP clone

template SSP OSCAL tables 現有資料為 Excel import 的副產品，不再做為 project clone source。

Excel 角色欄位

DB system_menus 存 OSCAL key（無中文）
FE oscal-role.json 存中文 label
BE OSCAL_PARTY_ROLE_ZH / sheet_handlers _PARTY_ROLE_ZH_TO_KEY 雙向對應
三者均為 source code hardcoded，OSCAL 標準角色不常變，可接受

---

---

---