SSP Docx Import Bug Arc (5/25 - 5/26) FIXED SUMMARY

---

User 反映 docx 重新匯入 module-frame/344ac369-916a-4e34-97ee-4d32ddc21cf3/template-edit（mf 379 / template SSP 278）後出現 4 大問題：

過程中發現 / 衍生 4 個 sub-bug：

---

FE（user 自行 commit + push 的）

✓ FE 兩 commit 已 push 到 origin/feature/ssp-oscal-alignment，working tree 乾淨。

BE（全 working tree 未 commit）

下列檔案累計本 arc 8 個 fix 的所有改動，等 user 拍板拆 commit 或一次包：

另有先前 P/Q/R arc 留下的 working tree（未在本 arc 動）：

• domain/oscal/strategy/module_frame_write_strategy.py
• domain/oscal/strategy/ssp_write_strategy.py
• pyproject.toml
• tests/test_module_frame_write_strategy_v2_parties.py
• 多份 P/Q/R 相關 changelog / handoff / implementation-plan 文件（已存在 docs/）

---

Bug 1：template-edit parties 編輯變新增 ✓ FIXED

Root cause：app/oscal/service/party_context_service.py:update_party() 改 role 時呼叫 _link_party() 只 add 新 role link，沒 delete 舊 role link → oscal_responsible_parties 表內同 party_uuid 留兩筆 link（舊 role + 新 role）→ list_parties() 把每筆 rps 都展開 → DataTable 顯示同名兩筆。

Fix：update_party 改 role 時，先查同 (party_uuid, context_type, context_id) 下所有 link，砍掉 role 不一致的，再 add 新 role。

Verify：✓ user 第一輪測試後回報「1 好了」。

---

Bug 2：人員角色預設 system-user ✓ FIXED

Root cause：_dict_to_parsed_parties line 1462-1468 對 docx 沒解出 role 的 party，hardcoded fallback：

• organization → "responsible-organization"
• person → "system-user"

Fix：拿掉 fallback，role=p.get("role") or "" — docx 沒給就保持空。寫入路徑 _upsert_responsible_party 已 normalize None → '' 並接受空 role 寫 link（schema role_id VARCHAR NOT NULL，'' 合法）。

未動：party_context_service._validate_payload 仍擋 manual CRUD dialog 空 role（template-edit 手動編輯人員 dialog）— 本期不在 scope。

---

Bug 3：Step 2 現值空白 ✓ FIXED

Root cause：_load_current_v3_lists line 1608-1609 對 source_type == "module_frame" 硬 return empty — 註解寫「no template SSP yet → all-empty」假設首次匯入，但對「重新匯入既有 mf」情境（template SSP 已存在）錯誤 → diff 比對沒 current_values → FE 顯示「現值」空白。

Fix：module_frame 分支改走 _ssp_shell_service.resolve_existing_shell(source_uid) 取既有 SSP id（read-only，不 materialize）→ 找到走 project_ssp 同路徑 query 4 v3 lists；找不到（首次匯入）→ catch PreconditionFailedError → return empty。

---

Bug 4：系統依賴元件無法寫入 ✓ FIXED

Root cause：_apply_v3_decisions line 1197-1203 對 diff_status="added" 且無 user decision 的 row → drop（防呆 default）。FE 沒送 components_decisions / leveraged_authorizations_decisions 時，所有 added rows 全 silent drop → 對重新匯入的 mf，components / LA / inventory 全沒寫進 DB。

Fix：added × no decision 改 inject parsed_values（mirror parties default + SC default 行為，符合 user「從無到有 docx 帶來就該寫入」直覺）。

例外：

• action="skip" → drop（user 明確跳過）
• action="keep_current" → drop + log warning（added 表 DB 沒值，無從 keep — 矛盾指令）

---

Sub-bug A：Step 3 PartiesSection readonly regression ✓ FIXED（FE）

Root cause：commit 0c8fe93 feat(ssp-update-diff): PartiesSection respects parties_decisions 加 isPartyReadonly() — 對 keep_current action 的 party，整個 row 含 Dropdown / 5 個 InputText / link button 全鎖 readonly → user 在 Step 3 完全無法編輯。

Fix（FE sections/PartiesSection.vue）：

• 拿掉 9 處 :readonly="isPartyReadonly(p.party_uid)"
• role Dropdown 永遠顯示（不再被換成 <span> 唯讀 label）
• onFieldEdit 改值時自動把該 party action 從 keep_current 切到 use_docx（user 改了就表示要採用 + 修改）
• 「保留現值」Tag 仍保留作為提示

---

Sub-bug B：Component LA link bug ✓ FIXED

Symptom：confirm 後 DB ssp_components.leveraged_authorization_uid 全 NULL，雖然 LA 確實寫進 DB（ssp_leveraged_authorizations 有 row）且 title 跟 component.leveraged_authorization_ref hex 完全一致。

Root cause 推測：ComponentWriteStrategy.write 走 self._la.get_all(...) 查剛被 LeveragedWriteStrategy.write 寫的 LA — 雖然 base repo add() 已 flush，但 jedi-oscal / SQLAlchemy session 配置下同 transaction 內後續 get_all 在某些路徑下拿不到剛 add 的 row → la_title_to_uid 空 → 對不上 → 寫 NULL。

Fix：改 architecture 跳過 DB query：

• LeveragedWriteStrategy.write signature 改返 tuple[int, dict[str, uuid.UUID]] — 第二個元素是剛 add 的 LA title → uid map
• ComponentWriteStrategy.write 加 optional la_title_to_uid 參數；caller 傳就用、不傳走 DB get_all（backward compat for legacy callers）
• confirm_service.confirm LA write 後 unpack tuple，把 map 餵 Component write

3 個 test 同步更新（test_ssp_write_strategy.py 2 個 + test_ssp_import_confirm_service.py 1 個）。

---

Sub-bug C：Step 3 parties 顯示 0 / 0 ✓ FIXED（FE）

Root cause：store _defaultPartyAction(party) / _defaultV3RowAction(row) 對 diff_status 為 changed 或 unchanged 的 row 預設 'skip'（「防誤動」設計）→ Step 3 PartiesSection 用 isPartySkipped(uid) filter 全濾掉 → 顯示「未識別出單位 / 未識別出人員」。

Fix（FE stores/sspDocxImportStore.js）：

• _defaultPartyAction / _defaultV3RowAction 對 changed / unchanged 改返 'keep_current'（不 'skip'）
• added 仍 use_docx、gone 仍 keep_current（不變）

效果：

1. Step 3 PartiesSection 顯示所有 parties 給 user 編輯
2. BE _apply_v3_decisions changed × keep_current → inject current_values → 不覆寫 DB 既有資料
3. Step 2 SelectButton 預設從「跳過」變「保留現值」(防誤動精神維持)

---

Sub-bug D：Diff 永遠標 changed（user 困擾「為什麼還有衝突」）✓ FIXED

Symptom：image #6 SC status 現值=active / 新值=空 標 changed；image #9 component leveraged_authorization_ref 現值=空 / 新值=有 標 changed。User：「都不該算差異 / 一個是 docx 沒給該繼承、一個是自動補資料」。

Root cause：_compare_scalar_fields (v3) 跟 compute_party_diff 內 loop 對任何欄位不相等都標 changed — 沒考量「一方空」case。

Fix：兩處比對邏輯都加「任一方空 → 不算差異」（對稱 symmetric）：

• par 空 + cur 有 → 不算差異（docx 沒給 = 不修改）
• cur 空 + par 有 → 不算差異（DB 沒值 + docx 補資料 = 自動 backfill）
• 兩邊都有不同 → 真實差異
• 兩邊都同 → equal

但「自動 backfill」要真實寫入，所以加 _apply_v3_decisions 內 inner helper _merge_backfill(cur, par)：對 cur 內空欄位用 par 補。unchanged path 跟 changed × keep_current/skip path 都走 backfill。

效果：

• UI 不再標假衝突
• DB 自動 backfill 空欄位（典型場景：component.leveraged_authorization_uid NULL → docx 帶 link → 自動補上）

---

Sub-bug E：SC status default 'active' (revert) ✓ DONE

過程：我一開始把 _dict_to_parsed_system_characteristic 加 status=... or "active" fallback 滿足 user「狀態為空時要有預設」要求。但 user 澄清：「word 沒給就繼承現值」不是「fallback 預設值」。

Fix：revert or "active"，由 FE _defaultV3RowAction 預設 keep_current + BE _apply_v3_decisions SC keep_current 把 parsed_result.system_characteristic = None 略過 SC write → DB 既有 active 保留。

---

對既有 mf 重 docx import → Step 2 解決差異 tab：受評標的 / 系統元件 / 外部利用服務 顯示 DB 現值，docx 沒給的欄位不再標假衝突；Step 3 預覽頁所有 5 parties 顯示且可編輯角色 / 名稱；confirm 後 component 自動 link 到對應 LA、空欄位繼承現值不被空蓋掉、added rows 預設寫入。

---

• 對話紀錄歸檔 → docs/conversation-history/2026-05-25/ssp-docx-import-bug-arc/（8 sessions）+ docs/conversation-history/2026-05-26/ssp-docx-import-bug-arc/（2 sessions）
• SUMMARY 報告（本檔）
• design.md §11.X 新段（待 user 下令後補）
• changelog（待 user 下令後補）
• memory feedback 新教訓（待 user 下令後補）
• BE commits（全 working tree 未 commit，等 user 拍板）

---

---

---

---

---

---

等 user 拍板：

1. BE 改動是否要 commit（建議拆 4 個 commit：Bug 1 / Bug 2 / Bug 3+4 / sub-bug B+D；或一次包成 1 個 fix arc commit）
2. 是否要補 design.md §11.39-46 段
3. 是否要寫 changelog
4. 是否要寫 4 條 memory feedback
5. 是否要 push（per CLAUDE.md「push 永遠要 user 明確指示」）