問題現場
這個案子要對 Wi-Fi 模組的追蹤資料做 LLM 摘要，但來源 Excel 本身有些地方需要先修整。難點不在「叫 AI 摘要」，而在修整與回寫的安全：
- 修整時不能把原意弄壞（例如把承載語意的換行當空白壓掉）。
- 回寫資料庫時不能更新到錯的列，也不能改壞、改了無法還原。
換句話說，這是一個「先把食材處理乾淨、又不能切到手」的問題。
最小技術背景
- 資料保真（data fidelity）：修整資料時不破壞原意；「整理換行」不等於「把空白全壓掉」。
- 對位（row 對應）：用穩定的 key 把「來源某一列」對到「資料庫某一筆」，避免更新錯對象。
- dry-run / apply：先只產生「會改哪些」的差異清單（dry-run），確認後才真的寫入（apply）。
- idempotence（重跑不變）：同樣的東西再跑一次，幾乎不該再有改動；若第二次仍大改，代表流程不穩。
系統架構與資料流
更新資料庫的每一步都可預覽、可備份、可還原；最後用「重跑幾乎 0 變動」自我驗證：
flowchart TD
XL["Excel 來源"] --> FIX["修整｜保真：整理換行 ≠ 壓掉空白"]
FIX --> MAP["對位｜source_file + row_idx_excel"]
MAP --> DRY["dry-run｜產生 diff 預覽"]
DRY --> BK["備份受影響列"]
BK --> APP["per-file 交易式套用"]
APP --> DB["MySQL"]
DB --> SUM["LLM 摘要｜在乾淨資料上進行"]
APP --> IDEM{"第二次重跑 ~0 updates?"}
IDEM -->|是| OK["穩定 / idempotent"]
IDEM -->|否| CHK["有不穩，回查"]
關鍵設計決策（含取捨）
| 決策 | 選了什麼 | 否決的替代 | 為什麼 |
|---|---|---|---|
| 順序 | 先保真、再摘要 | 直接把原始 Excel 丟給 LLM | 否決：來源一被壓壞，下游摘要就救不回來了 |
| 修整定義 | 整理換行，但保留語意空白 | 一律 whitespace flatten | 否決：等於把語意當雜訊抹掉 |
| 對位 | source_file + row_idx_excel 複合 key | 用單一欄位值對位 | 否決：值一重複，就會對到錯的那一列 |
| 寫入 | dry-run → 備份 → 交易式 apply | 直接覆寫 | 否決：改錯了就再也還不了原 |
代表性技術證據
可逆更新（pseudo-code，示意）
plan = build_diff(rows, key=["source_file", "row_idx_excel"]) # 用複合 key 對位，避免認錯人
review(plan) # dry-run：先看看會改到哪些，別急著動
backup(plan.affected) # 受影響的列先備份起來
for f, changes in plan.by_file(): # 一個檔案包成一個交易
with db.transaction():
db.apply(changes) # 出錯 → 整個交易整批退回
# idempotence 自我驗證：再跑一次，diff 應該幾乎是空的
assert len(build_diff(rows, key=KEY).changes) == 0合成範例（示意）：來源含 "log line A\nlog line B"，修整後仍是兩行；若某次「修整」把它變成 "log line A log line B"，就是把語意壓掉了——應在保真檢查時被擋。
踩過的坑
| 欄位 | 內容 |
|---|---|
| 症狀 | 套用後，部分列的內容對到了錯的資料 |
| 初判（猜錯） | 第一個念頭是 LLM 摘要出錯 |
| 驗證 | 追 row 對位，發現用單一欄位對位、在重複值時對錯了列 |
| 根因 | 對位 key 不唯一 |
| 修法 | 改用 source_file + row_idx_excel 複合 key |
| 預防 | dry-run diff 須人工看過才 apply；並以「第二次重跑 ~0 updates」驗穩 |
驗證方式
- 保真：含多行的合成列，修整後語意換行仍在（不被壓平）。
- 對位：重複值情境下，複合 key 仍對到正確列。
- 可逆：dry-run 先出 diff、備份後才交易式 apply，失敗整批退回。
- idempotence（驗收標準）：第二次重跑的變動數接近 0。
可複製 SOP：安全地修整並回寫資料
適用情境：要修整來源資料並更新到資料庫，且不能改錯、改壞。
不適用情境：純新增、無覆寫風險時可簡化。
前置條件
- 一組能唯一對位的 key（必要時用複合 key）。
- 備份與交易能力；一組含多行 / 重複值的合成資料當基準。
步驟
- 先定義保真：先講清楚哪些東西算「語意」（這裡是換行），修整時一定要留著。
- 複合 key 對位：用一個能唯一定位的 key，免得更新到錯的列。
- dry-run 先看：先產生 diff 預覽，人眼確認過再真的動。
- 備份再套用：先備份受影響的列，一個檔包一個交易寫入，出錯就整批退回。
- 重跑驗穩：再跑一次看看，變動應該接近 0，不然就是還不穩。
停損點
- dry-run diff 出現預期外的大量變動 → 停，先查對位 / 修整。
- 第二次重跑仍大量變動 → 停，流程不穩，不可信任。
驗收標準
- 對位正確、語意保真、可還原；重跑接近 0 變動。
回滾：套用前的備份即還原點；以交易為單位，失敗整批退回。
可複製到：任何「修整來源資料並安全覆寫資料庫」的場景。
決策回放（三個月後回讀用）
- 背景：LLM 摘要前要先修整 Excel 並安全回寫，不能改錯改壞。
- 限制：不可外流真實追蹤資料與供應商名；覆寫須可預覽、可備份、可還原。
- 考慮過但放棄：直接 whitespace flatten 完就入庫——被「破壞語意」否決；還有單欄位對位——被「重複值會對錯」否決。
- 證據：複合 key 對位、dry-run diff、交易式 apply、idempotence 重跑驗證。
- 未解：保真檢查到底覆蓋多廣；跨供應商要不要共用同一套修整 / 回寫框架。
作者備註： 「重跑一次看還會不會變」是我很愛的低成本驗證——它幾乎不花力氣，卻能立刻告訴你流程到底穩不穩。