從一個 Outbox 開始：讓主交易不被外部系統拖住

問題

POS 與 CRM 要同步商品、分類、原料與交易。最直接的做法是 POS 寫入時順便呼叫 CRM API。CRM 暫時失敗，POS 結帳就跟著失敗；CRM 慢，收銀台就慢。

設計目標

• 門市作業只依賴自己的資料庫。
• 同步失敗可以重送，重送不會產生重複資料。
• CRM 持續故障時，不要一直打它。

架構

POS ──▶ POS Database ──▶ Outbox（記錄同步事件）
                            │
                            ▼
                      Queue Worker ──▶ 簽章請求 ──▶ CRM
                            ▲                        │
                            └──── 成功 / 失敗 ◀───────┘

主交易與 Outbox 記錄在同一個資料庫交易裡寫入。交易成功，事件一定存在；交易失敗，事件也不會留下。

Worker 要處理的四件事

• Retry 與 Backoff：失敗後等一段時間再試，間隔逐次拉長，超過次數進 Dead Letter。
• Idempotency：每個事件帶唯一鍵，CRM 端用它擋掉重複建立。
• HMAC：請求簽章，CRM 端驗證來源。
• Circuit Breaker：連續失敗到門檻就暫停送出，過一段時間再試探。

心得

• Outbox 的價值不在複雜，而在把「一定要做」和「現在做不到」分開。
• 第一次重送時發現冪等鍵設計得太粗，把不同門市的同一商品當成同一筆。鍵要包含租戶。