服務路徑與語意分層

這條路徑是 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。

本篇以 5.2 Kubernetes 部署策略 與 5.3 load balancer 合約 為前置知識——rollout 批次、probe 對齊、drain contract 等概念在該兩篇定義，本篇直接操作化。lifecycle 狀態的完整定義見 5.6 Platform Lifecycle Contract。

服務路徑與切換責任

這條路徑是 client -> load balancer -> checkout-api -> payment provider/order db/order event。部署期間新舊版本會同時承接流量，核心風險在流量生命週期是否可收斂，image 替換本身反而是最可預測的部分。

切換責任分三層：

1. 版本可啟動：container/runtime/config 可用。
2. 版本可接流量：readiness 與依賴狀態對齊。
3. 版本可退場：drain 與在途請求可收束。

Preflight：先驗證可服務基線

Preflight 的責任是把「可啟動」與「可服務」拆開驗證。最小檢查包含：

1. image 與 runtime config 版本對齊。
2. secret 已注入且權限正確。
3. startup/readiness probe 能反映真實依賴狀態。
4. load balancer contract 參數與服務期望一致。
5. service discovery 註冊與摘除路徑可用。

Preflight 失敗時不進 canary。先把失敗收斂在控制面，避免切流後才發現版本不可服務。

Preflight 自動化

手動 preflight 在低頻部署時可行，部署頻率上升後會成為瓶頸或被跳過。穩定做法是把 preflight 檢查嵌入 CI/CD pipeline 的 pre-deploy stage：

1. image 與 config 版本對齊檢查：pipeline 比對即將部署的 image tag 與 ConfigMap / Secret 版本是否在相容矩陣內。版本矩陣可維護在 git（如 deploy/compat-matrix.yaml），CI 自動比對。
2. infra drift detection：部署前用 IaC 工具（Terraform plan、Crossplane drift check）掃描目標環境的實際狀態是否跟宣告狀態一致。drift 存在時暫停部署——在已漂移的環境上部署新版本，會把漂移與版本變更的影響混在一起，事故時無法分辨根因。
3. probe 語意驗證：在 staging 環境對新版本觸發 startup → readiness → liveness 全流程，確認 probe 回應與依賴就緒條件吻合。這步抓的是 probe 設定退化（如 readiness endpoint 被改成永遠回 200）。
4. rollback 可行性驗證：確認舊版本 image 仍在 registry 且可拉取、舊版本 config 仍相容。rollback 能力在 preflight 階段驗證，比事故時才發現「舊版拉不到」代價低得多。

Preflight 自動化的產出是一份 go/no-go 報告，進入 6.8 Release Gate 作為放行依據。pipeline 中的 preflight stage 失敗應阻擋部署而非產生警告——可忽略的 preflight 等於沒有 preflight。

Canary Batch 與 Stop Condition

小流量先驗證新版本行為，再決定是否擴批——Canary 回答的是「這個版本值不值得擴大」。

canary 判讀要維持 per-version 視角。只看整體服務平均值會掩蓋新版本局部退化。

Traffic / Drain：把退場變成可驗證流程

Drain 的責任是讓舊版本在下線前完成在途請求，不讓 rollout 把短暫切換放大成用戶錯誤。

退場順序：

1. 舊實例 readiness 先轉 not-ready 停接新流量。
2. 保留 drain 窗口完成 in-flight request。
3. 確認連線數下降到門檻後再終止進程。
4. 驗證無異常 reconnect 尖峰再進下一批。

Drain 條件的完整 workload 分類回到 5.6 Platform Lifecycle Contract，本段以 checkout service 為例：短 API 的 draining 窗口可短，長輪詢與 webhook callback 要更保守。

Rollback Compatibility

舊版本回來時仍可運作，是 rollback 能成立的前提——回退如果變成第二次故障，就失去了回退的工程價值。

要先驗證四個相容面：

1. config 相容：新設定不會讓舊版啟動失敗。
2. schema 相容：資料結構仍可被舊版讀取。
3. cache key 相容：舊版可讀新快取或有 fallback。
4. event schema 相容：舊版 consumer 不會因新事件欄位崩潰。

若這四項未完成，所謂 rollback 只會停在「版本回切」，無法恢復服務正確性。

Evidence Package

每一批切換要可被判讀、可被追責、可被回放——部署 evidence 支撐這三個條件。

這份 evidence 要對齊 4.20 Observability Evidence Package。

Release Gate

Release gate 的責任是決定下一批切換與是否凍結 rollout，不是報告「目前看起來正常」。

這組欄位要對齊 6.8 Release Gate。

Incident Decision Log

freeze rollout、rollback version、隔離 region、延長 drain 都屬事故決策，需寫入 8.19 Incident Decision Log。涉及流量規則 / control plane 設定推送的決策、見 5.7 跟 8.23 Control Plane Decision Log。

 1incident_decision:
 2  timestamp: 2026-05-11T15:06:00Z
 3  decision: "freeze rollout at 25% and rollback one region"
 4  context: "new version timeout to payment provider increased in ap-northeast"
 5  evidence:
 6    - query: checkout_error_rate_by_version_region
 7    - query: payment_timeout_ratio_by_region
 8  owner: release-incident-commander
 9  expected_effect: "contain customer impact and restore baseline success rate"
10  rollback_condition: "timeout ratio does not recover after rollback batch completes"

Case Write-back 與邊界

這篇回寫對齊 5.C9 反例、5.C1 Tradeshift 與 5.C3 Orbitera：前者看切換失序，後兩者看遷移路徑與回退策略。preflight / canary / drain 各階段的生命週期定義回到 5.6 Platform Lifecycle Contract。

這篇不處理 schema migration 本身、cache stampede 或 queue replay。若核心風險在資料正式狀態、快取回源或事件恢復，路由到 1.7 Schema Migration Rollout 證據、2.9 Cache Migration 與 Stampede Rollback 或 3.8 Queue Consumer Retry 與 Replay Handoff。

核心論點

事故回寫的核心概念是把一次事件轉成長期能力。回寫完成後，下一次同類事件會在更早階段被辨識與收斂。

回寫層級

回寫欄位

回寫欄位的責任是讓教訓可重用。每次回寫至少記錄事件訊號、決策原因、成本影響、改進方案、驗收條件與下一次檢查點。

與產品決策連結

與產品決策連結的責任是讓安全改進進入 roadmap。高影響教訓可轉成設計約束、放行條件與資源分配調整。

與架構決策連結

與架構決策連結的責任是讓技術改進可追溯。回寫到架構時需標示控制責任、邊界改動與相依影響。

與知識網連結

與知識網連結的責任是讓教訓可查詢。回寫結果可同步更新 7.x 章節、藍隊素材庫與知識卡片連結。

素材回寫入口

素材回寫入口的責任是把 field case、scenario 與 control pattern 轉成文章更新路由。案例提供壓力，情境提供演練，控制模式提供可搬運欄位。

判讀訊號與路由

必連章節

• 7.B5 Detection Engineering Lifecycle
• 7.B6 Incident Triage Loop
• 7.B9 Blue Team Scenario Library
• 7.B12 Defender Pressure From Real Incidents
• 7.21 資安如何成為服務設計輸入
• 7.26 資安素材庫如何支援工程推演

完稿判準

完稿時要讓讀者能把事故教訓寫成回寫任務。輸出至少包含回寫層級、回寫欄位、產品路由、架構路由與知識路由。