stable · guide · 0.1.0
Channels、delivery outcome 與 retry
Channel resources
- email 使用已驗證 email Delivery Endpoint、核准 Sender Profile 與 versioned template。
- FCM 與 APNs 使用 client-scoped push endpoint，不向 Project Backend 暴露 provider credential。
- LINE 使用已核准 provider profile 與 endpoint identifier。
- Web Push 只接受 HTTPS subscription 與允許的 endpoint host。
撤銷 consent、未核准 Sender Profile、失效 endpoint 或不相符 template 會阻止建立或抑制 Delivery。
Delivery outcomes
pending 或建立成功只表示 durable work 已保存。使用
GET /notification-deliveries/{deliveryId}
查詢 email 或 channel Delivery。狀態與終止性如下：
| Status | 意義 | 終止性 |
|---|---|---|
pending |
已持久化，等待 worker | 否 |
retry |
暫時失敗，已排程重試 | 否 |
accepted |
email provider 已接受，仍等待最終事件 | 否 |
sent |
provider 呼叫成功；非送達證明 | channel 是；email 為暫時觀察值 |
delivered |
email provider 回報送達 | 暫時；之後仍可能 bounce 或 complain |
rejected |
provider 拒絕請求 | channel 是；email 為暫時觀察值 |
suppressed |
consent、endpoint 或 policy 阻止傳送 | 是 |
unavailable |
email provider 回報收件端無法使用 | 暫時；較高優先序事件仍可取代 |
bounced |
email provider 回報退信 | 暫時；complaint 仍可取代 |
complained |
email provider 回報垃圾郵件投訴 | 是 |
unknown |
呼叫結果不確定，禁止自動重送 | channel 需對帳；email 仍可能收到 webhook |
failed |
重試耗盡並進入 dead-letter | channel 需對帳；email 晚到的 webhook 仍可更新 |
email provider webhook 可能在送出請求之後，以 accepted、rejected、unavailable、delivered、bounced 或 complained 更新 Delivery。
在 provider observation window 關閉前，email outcome 應視為可依事件優先序更新的觀察值；不要只以一次 GET 回應推斷永遠不再變化。
unknown 表示 provider 呼叫結果不確定，不能直接重送同一業務通知。保留原本的 delivery_id 供營運對帳。
Retry semantics
Retryable provider failure以 exponential backoff 排程，延遲約為 2^attempts 分鐘並有上限。每次 attempt 都獨立記錄；worker lease 遺失不會刪除工作。超過最大次數後 durable operation 進入 dead-letter，由 Platform Operator 對帳，不由 Project Backend 以新 Idempotency-Key 重複建立 Intent。
Redis 只負責喚醒或加速；即使 Redis 遺失，PostgreSQL scanning 仍會找回待處理 Delivery。