Event Contract

Event contract 的責任是定義 producer 發出的事實、consumer 能依賴的欄位，以及版本演進時的相容窗口。最小 contract 包含 event id、schema version、occurred time、producer、entity id、dedup key 與資料保護範圍。

event id 讓訊息可追蹤；schema version 讓版本演進可判斷；occurred time 讓 replay 可分時間窗；dedup key 讓 consumer 可去重；PII scope 讓事件能接到資料保護。

event id 支撐 incident timeline 與重複投遞判讀。schema version 支撐新舊 consumer 共存。occurred time 支撐 replay window 與對帳查詢。dedup key 支撐 idempotency。PII scope 支撐 audit 與資料保護。這些欄位先成立，broker retention 或 partition 設計才有可依附的語意。

Schema Compatibility

Schema compatibility 的責任是讓 producer 與 consumer 可以分批升級。新增欄位要保留 optional，移除欄位要有相容窗口，語意改變要用新 version 或新 event type。

序列化能解析是相容性的第一層。若欄位仍存在但語意改變，consumer 仍可能產生錯誤副作用。這類變更需要在 release gate 中驗證。

Replay Boundary

Replay boundary 的責任是限制重播範圍，避免修復動作擴大事故。Replay 要能指定 time range、tenant、partition、event type、schema version 與 downstream capacity。

replay window 要和 time range 與 query link 對齊，讓事後能回放當時重播的是哪一批事件。

Compensation

Compensation 的責任是處理副作用已經發生但結果不正確的情況。寄信、發票、付款通知與 webhook 都可能需要補償，重播是其中一種恢復方式。

補償前要先判斷副作用是否可逆、是否會通知使用者、是否需要人工審核。不可逆副作用要比可重播副作用更早接到 Incident Decision Log。

跨 broker 業務語意對映

跨 broker migration 的工程責任是維持業務語意對映、broker 吞吐是次要驗證項。同一份 event contract 在 Kafka、Pub/Sub、SQS、NATS 的對映概念不同、需要逐項校準。

對應 9.C9 Spotify Kafka → Pub/Sub Migration — Spotify 7500 萬用戶事件交付系統遷移、case 明確點出 Kafka 的 partition / offset / consumer group 對映成 Pub/Sub 的 subscription / ordering key / message attribute、需要校準業務語意而非直接搬。

典型概念對映差異（依據 9.C9 case 列出的三組對映展開、Pub/Sub 實際 API 細節為文章補充）：

• Partition (Kafka) 跟 Subscription (Pub/Sub)：Kafka partition 是物理分片 + 順序邊界；Pub/Sub subscription 是邏輯 fan-out、無物理分片概念。靠 Kafka partition 保證 per-key 順序的 consumer、遷到 Pub/Sub 改用 ordering key
• Offset (Kafka) 對映成 message attribute (Pub/Sub)：9.C9 case 原文對映方向；replay 模型差異上、Kafka offset 是位置指標、可任意回放到某個 offset；Pub/Sub 用 Snapshot + Seek API 達成類似 replay 能力、模型不同
• Consumer Group (Kafka) 跟 Subscription (Pub/Sub)：Kafka consumer group 內部 rebalance 自動分 partition；Pub/Sub subscription 自動分 message、語意接近但 rebalance 細節差異會影響 in-flight message 處理順序

遷移評估要驗證的業務語意：

• 順序保證：原系統靠 partition / consumer group 保證什麼順序、新系統能否複製
• Replay 模型：原系統 replay 方式、新系統的 replay 工具能否達成同範圍。replay window 上限由 idempotency 保留期反推、見 3.6 Replay 跟 Idempotency 共設計
• 失敗模式：consumer 故障時、原系統的 rebalance / redelivery 行為、新系統會不會差異

判讀重點：broker migration 屬語意對映工程、吞吐能力比較是次要驗證項。對應 3.3 outbox pattern 的「Broker 遷移階段流程」、實作面用 dual-write + shadow consume + cutover、驗證面靠 event contract 跟 replay 邊界做對帳。

跨模組路由

1. 與 03 內部：replay window 跟 idempotency 共設計回到 3.6 processing-recovery-semantics；broker 遷移階段流程回到 3.3 outbox pattern
2. 與 04 的交接：event contract 演進 + replay 邊界進 4.20 Observability Evidence Package
3. 與 06 的交接：event contract 跟 replay 驗證進 6.12 Idempotency 與 Replay 驗證 跟 6.23 Verification Evidence Handoff
4. 與 07 的交接：event payload 的 PII / audit 邊界進 7.4 data protection and masking

選型前判準

Broker 選型前要先回答：

1. event contract 是否能支援版本相容。
2. consumer 是否能用 dedup key 判斷重複。
3. replay window 是否能用查詢與指標證明。
4. 不可逆副作用是否有補償流程。
5. event payload 是否包含 PII 或 audit-sensitive 欄位。

這些問題決定後續要比較 broker retention、schema registry、DLQ、partition 與 replay 工具，並把吞吐放回服務語意下判讀。

實體服務討論承接點

實體 broker 文章要承接本篇的 event contract 與 replay boundary。Kafka 的長期 retention、RabbitMQ 的 routing 與 DLQ、SQS 的 visibility timeout、NATS JetStream 的 stream/consumer 模型，都要放回事件契約與重播邊界下判讀。

若事件需要長期 replay，後續文章要比較 retention、offset、partition 與 schema evolution。若事件主要是工作任務，後續文章要比較 visibility、ack、DLQ 與重試治理。若事件包含 PII 或高風險副作用，後續文章要比較 audit、encryption、access control 與補償流程。

下一步路由

要處理 outbox 與事件發布一致性，接著讀 3.3 outbox pattern 與發佈一致性。要處理 consumer 端去重與重播，接著讀 3.4 consumer 設計與去重。

服務路徑與語意分層

這條路徑是 order-service -> broker -> order-created-consumer -> invoice/email/search/webhook。Producer 把事件交給 broker 後，真正的業務完成要看 consumer 是否正確提交副作用。

這篇先固定三層語意：

1. Delivery semantics：訊息是否投遞與確認。
2. Processing semantics：副作用是否可承受重複與部分失敗。
3. Recovery semantics：故障後是否可重播並恢復一致。

ack/nack 成功只代表 delivery 進度，不代表發票與通知已完成。

Event Contract 與相容邊界

Event contract 的責任是讓 producer 與 consumer 在版本演進時仍可互通，且可被觀測與回放。

order_created 最小欄位：

1. event_id：全域唯一識別。
2. schema_version：事件版本。
3. occurred_at：事件發生時間。
4. order_id、tenant_id：業務定位。
5. idempotency_key：副作用去重鍵。
6. pii_scope：敏感欄位範圍。

版本演進採向後相容優先：新增欄位可選、舊欄位保留窗口。schema 演進前要先確認 consumer 端 fallback 解析邏輯存在，避免切版後整批進 DLQ。

Retry / DLQ / Quarantine

Retry 的責任是吸收暫時性故障，不把短暫抖動升級成事故。這條路徑使用有限重試 + backoff + jitter：

DLQ 的責任是隔離與診斷，不是永久儲存。重點是把異常訊息分群後對應修法，修完再定向回放。

Idempotency 與 Ack Timing

Idempotency 的責任是把 at-least-once 交付轉成可接受業務結果。副作用如發票、email、webhook 都要以 idempotency_key 做去重。

Ack timing 的原則是「核心副作用提交後再 ack」：

1. 先執行副作用或落地可追蹤結果。
2. 成功後寫去重紀錄或 checkpoint。
3. 最後 ack broker。

先 ack 再副作用會造成資料遺失；副作用成功但去重紀錄失敗，則要由 recovery 層補償。

Replay Runbook

Replay 的責任是故障後在可控範圍內恢復，不把修復變成第二次事故。

這條路徑的 replay runbook：

1. 選定 replay window：依 occurred_at 與 schema_version 分段。
2. Dry run：先在影子通道跑去重與下游容量驗證。
3. 限速回放：按 tenant 或 partition 分批，監控下游錯誤率。
4. Reconciliation：對帳發票、通知、索引結果。
5. Stop condition：duplicate side-effect、downstream timeout、DLQ 再爆發即停。

replay window 要能被明確描述與回放，不可用「重播昨天全部」這種不可驗證句子。

Job queue 的拓樸分工

當背景工作同時要 高吞吐 跟 快速反應、單一通道模型會變成瓶頸。job queue 的擴展通常是 拓樸重整、把不同工作類型切到不同傳遞路徑、而非單點替換。

對應 3.C5 Slack Job Queue 演進到 Kafka + Redis — Slack 在 job queue 擴展時把工作切到不同傳遞路徑、Kafka 跟 Redis 分別承擔持久性跟即時性目標、分開治理 lag、重試跟失敗重播。

拓樸分工的判讀（基於 Slack case 揭露的雙通道分工方向）：

• 持久性主導的 job（發票、付款通知、合規記錄）→ Kafka / 持久 queue、保證 at-least-once
• 即時性主導的 job（線上提醒、playback control、UI 更新）→ Redis / 輕量 queue、low latency

設計含義：同一 consumer 應專注單一目標（高吞吐 / 即時 / 持久擇一）、其他目標拆到對應路徑。對應 3.4 consumer-design 三個工程議題鐵三角 — idempotency / 重播流程 / 下游承載能力是 consumer 內部設計、拓樸分工是 跨 consumer 的責任拆分、兩者互補。

Job queue 規模差異的治理重點

不同規模服務的 job queue 治理問題差異大、SSoT 在本章。對應 3.C10 對照：規模差異下的佇列模型：

• 小型服務：優先用 managed queue（SQS / Pub/Sub）、運維成本最低。最容易忽略的是語意邊界（重試次數、死信規則、重播責任）、規模一上來會出現資料重複與漏處理。升級訊號：team 數超 3-5 個、各自寫 consumer 開始出現 idempotency 不一致、進中型階段
• 中型服務：常見問題是 lag 與 DLQ 長期累積。原因是 consumer idempotency + 重播流程 + 下游承載能力沒一起設計。對應前段 Job queue 拓樸分工。升級訊號：DLQ 累積速度高於排空速度連續 7 天、單一 tenant 流量尖峰拖垮其他 tenant、進大型階段
• 大型服務：需要處理跨租戶跟跨區壓力。單叢集思維會讓任何一類流量尖峰拖垮整體。對應 3.C4 LinkedIn Tiered Clusters 跟 3.1 broker-basics 分層治理平台、重點從「怎麼送訊息」轉成「怎麼隔離失敗」

判讀重點：當前服務規模決定要處理的 主要 問題。規模尚小的服務硬上 multi-tenant 隔離治理屬過度設計、規模化服務應同時考慮 broker 容量是否充足跟隔離邊界是否完整。判斷自己在哪個階段、看 升級訊號 對應的指標。

Evidence Package

Queue evidence 的責任是證明「投遞可達」與「處理可恢復」兩者同時成立。

這份 evidence 要對齊 4.20 Observability Evidence Package 與 6.23 Verification Evidence Handoff。

Release Gate

Queue release gate 的責任是決定是否擴大回放或恢復主通道，而不是只看單一 lag 指標。

這組欄位對齊 6.12 Idempotency 與 Replay 驗證 與 6.8 Release Gate。

Incident Decision Log

pause consumer、drain DLQ、啟動 replay、停止 replay、執行補償都屬事故決策，需寫入 8.19 Incident Decision Log。

 1incident_decision:
 2  timestamp: 2026-05-11T13:18:00Z
 3  decision: "pause invoice consumer and start scoped replay for tenant A"
 4  context: "duplicate invoices increased after consumer version rollout"
 5  evidence:
 6    - query: duplicate_invoice_ratio_tenant_a
 7    - query: dlq_events_by_schema_version
 8  owner: queue-incident-commander
 9  expected_effect: "stop duplicate side effects and restore invoice consistency"
10  rollback_condition: "duplicate ratio does not decrease within two replay batches"

Case Write-back 與邊界

這篇回寫對齊 3.C9 反例，重點是切換時語意分層混淆導致 delivery 成功但業務結果失真。

這篇不處理同步 API latency、cache TTL 或 deployment drain。若風險在同步交易壓力、快取失效或流量切換，路由到 4.22 Checkout API Evidence Package、2.9 Cache Migration 與 Stampede Rollback 或 5.8 Deployment Rollout with Drain and Rollback。