Bugfix Session 3 SUMMARY — Excel Update Flow 覆蓋語義修補

時程：2026-05-21（接續同日 session 2 SUMMARY：2026-05-21-bugfix-session2-SUMMARY.md） 跨 repo：compliance-manager-be + compliance-manager-fe

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

Excel re-import（update flow）時，舊資料沒有被覆蓋（append 而非 overwrite），以及基本資料 / 控制項清單沒有隨 Excel 更新，本次統一修補。

2. 修補項目與根因

#	Bug 描述	根因	修正位置
1	Re-import devices/info_systems/leveraged → 重複 row	`WriteStrategy.write()` 只 add，未先刪舊 row	`write_strategy/base.py`
2	取消勾選的控制項 default 殘留	`write_excel_control_defaults()` 只 upsert	`module_frame_write_strategy.py`
3	移除的參與人員 link 殘留	`write_parties()` 只 upsert，stale link 未刪	`module_frame_write_strategy.py`
4	Template-edit 控制項清單不隨 Excel 更新	`_confirm_update_flow` 未更新 `oscal_profile.include_controls`（頁面讀 profile，非 defaults）	`ssp_excel_import_app_service.py`
5	基本資料（名稱/類別/描述）不隨 Excel 更新	`_confirm_update_flow` 未呼叫 `update_module_frame()`；即使呼叫也需傳 `locale`，否則只改主表不改 `module_frame_trans`（failover query 優先翻譯表）	`ssp_excel_import_app_service.py`
6	導回 template-edit 時參與人員顯示舊筆數	`useModuleFrameParties` 永久 module-scope cache，import 後未 invalidate	`ImportExcelPreviewPage.vue` + `useModuleFrameParties.js`

3. Commit 清單（本次 session 3 未 commit，待使用者確認後提交）

BE 未 commit 的改動

app/oscal/service/ssp_excel_import_app_service.py — _confirm_update_flow + _resolve_include_uids_for_update
domain/oscal/service/write_strategy/base.py — delete-before-insert
domain/oscal/strategy/module_frame_write_strategy.py — full overwrite + stale link cleanup
di_containers/oscal/oscal_containers.py — refdoc_mapping_domain_service 注入

FE 未 commit 的改動

src/views/module_frame/ImportExcelPreviewPage.vue — confirm dialog + parties cache invalidate
src/config/locales/i18n/*/ssp-excel-import.json — confirm_overwrite_* keys

Changelog

docs/changelog/2026-05-21-fix-ssp-excel-import-overwrite-mode.md（已建立）

4. 架構關鍵決策

WriteStrategy 整份覆蓋 vs upsert

devices / info_systems / leveraged：整份覆蓋（delete all + insert）— 因為 row 本身無穩定 natural key，重複 row 無法去重
control_defaults + objectives：整份覆蓋（先清空 MF 全部 defaults + refdoc mappings，再只寫 in-profile 的）
responsible_party links：snapshot → upsert → 刪 stale（有 party_uuid 可追蹤，不需全刪全插）
reference_documents（程序書）：保持 append-only（設計明確不覆蓋）

`module_frame_trans` locale 陷阱

BaseRepositoryImpl.update(entity, locale=None) 只改主表 module_frames
GET /module-frame/{uid} 用 failover query，優先讀 module_frame_trans（翻譯表）
解法：update_module_frame 必須傳 locale（user_context.locale fallback zh_Hant_TW）

5. Follow-up

項目	說明
Track B（SSP 匯出）	B1–B6 全部 pending，尚未開始
Design-A4.md §11.3	本次偏差已補入 §11.3
Cucumber E2E	A5 update flow 整份覆蓋行為尚無 regression test