从 Twilio/Sinch/Infobip/Vonage/…

在替换现有 CPaaS 供应商、把供应商代码或 webhook 处理器翻译成 Sent、或规划分阶段切换及其验证门禁时使用。

适用场景

解决思路

1. 按顺序处理五个翻译问题：先处理有序回退（ordered fallback）问题，因为它会静默地使成本翻倍且在测试中不可见。
2. 不要把有序 channel 数组直接移植到 Sent：Sent 的 `channel` 数组是广播列表，移植有序数组会为每个收件人-渠道对产生一条消息和一次计费，测试能通过但生产费用会成倍增加；正确做法是省略 `channel` 或发送 `["sent"]`，让平台自动路由，并在同一 `message_id` 上跨最多三组渠道与供应商对进行重路由。
3. 按状态词汇映射表翻译状态：`QUEUED` 对应 Twilio `queued`、Sinch `QUEUED_ON_CHANNEL`（已接受但未发送）；`ROUTED` 无对应项（已选路由，重路由时会再次触发）；`SENT` 对应 Twilio `sent`、Sinch `MESSAGE_SUBMIT`（仅表示已交给供应商）；`DELIVERED` 对应各家的 `delivered`（首次证明手机已收到）；`READ` 对应 Twilio `read`、Sinch `READ`（仅 WhatsApp 和 RCS）；`FAILED` 对应 `failed`、`undelivered`（可能仍会重路由，不一定是最终态）；`FILTERED` 对应 Twilio 错误 21610（退订）（策略门禁，绝不重试）；`BLOCKED` 对应账户级错误（账户前置条件，先修账户再重发）；`SCHEDULED` 无对应项（静默时段停放，会自动恢复）。
4. 重写把每个非送达终态都当作可重试的处理器：这类代码会重试同意阻止（consent block），属于合规失败而非 bug；同时把基于数字供应商错误码（如 Twilio 的 `21610`）的处理器改写为基于 Sent 的字符串 `error.code` 家族。
5. 重写 webhook 验证而非移植：Twilio 用 `X-Twilio-Signature`，对完整 URL 加排序后的 POST 参数做 base64 HMAC-SHA1；Sinch 对 `body.nonce.timestamp` 做 HMAC-SHA256，带四个 `x-sinch-webhook-signature*` 头，或用 OAuth 2.0；Infobip 用 Basic、对原始 body 做 HMAC-SHA256，或在通知配置上用 OAuth，且头名称由账户配置；Vonage 用 `Authorization: Bearer` 中的 JWT，或旧式 `sig` 参数；MessageBird/Bird 用 `messagebird-signature`，对 timestamp、URL 和 SHA-256 body 哈希做 base64 HMAC-SHA256；Sent 用 `x-webhook-signature: v1,{base64}`，对 `{x-webhook-id}.{x-webhook-timestamp}.{raw_body}` 做 HMAC-SHA256。
6. 实现 Sent 验证：签名密钥去掉 `whsec_` 前缀后对剩余部分做 base64 解码，用常量时间比较，拒绝时间戳超出 300 秒的请求；由于 Sent 不提供逐事件 id，去重键必须从 payload 语义推导；用 `sent-webhook-engineer` 构建接收器，而不是改造现有供应商的验证器。
7. 协调而非复制退订存储：切换前导出 incumbent 的抑制列表，把任一 incumbent 渠道上的任何退订视为 Sent 全局退订，绝不为了“清理”迁移数据而清除 `opt_out`；Sent 的十个默认关键词是 `STOP`、`CANCEL`、`UNSUBSCRIBE`、`QUIT`、`END`、`START`、`UNSTOP`、`SUBSCRIBE`、`HELP`、`INFO`，仅当去除首尾空白后的完整正文等于关键词时才匹配，因此 incumbent 特有的关键词需要自定义关键词条目。
8. 把 incumbent 的关键词匹配器改写为精确的本地同意镜像和审计机制，匹配器不得再次向 Sent 写入同意。
9. 重新注册而非转移模板与租户：WhatsApp 模板随 WABA 存在，迁移问题是 WABA 是否移动；位置占位符（`{{1}}`、`{{2}}`）在 Sent 中变为命名参数，因此每个传有序数组的调用点必须改为传命名映射；审批是异步的并以 `templates` webhook 事件到达，所以要在切换前而非切换中建立模板清单。
10. 按映射表翻译租户：Twilio 子账户、Infobip Application 或 Entity、Sinch Conversation API app 都对应 Sender Profile；Twilio Messaging Service 对应路由加 profile 配置而非调用方池；每租户的供应商 API 凭证对应 profile 作用域 API key，或带 `x-profile-id` 的组织 key。
11. 按迁移顺序执行：1) 用 `scripts/inventory_scan.py` 机械地盘点每个发送调用点、webhook 处理器、状态分支、模板、抑制列表和凭证；2) 用 [references/provider-mapping.md](references/provider-mapping.md) 映射每一项，把有序回退数组和数字错误码标记为必须重写；3) 并行搭建 Sent：凭证、每环境一个 webhook、已验证的接收器、模板重新注册并获批；4) 用 `"sandbox": true` 在沙箱证明等价性，再用小规模真实队列确认到 `DELIVERED`；5) 用流量拆分双跑，比较同一消息类别上的送达率、延迟和每条消息成本；6) 按消息类别切换，风险最低的事务性消息优先、营销最后，保持 incumbent 接收器在线；7) 只有在完整计费周期数据干净后才下线，然后吊销 incumbent 凭证。
12. 避免这些能通过测试的错误：移植有序 channel 数组（成本翻倍且不报错）；把 `FILTERED` 当作可重试（合规风险）；复用 incumbent 的签名验证器（每次投递都返回 401）；假设 `202` 表示已送达（Sent 只确认已接受）；保留位置模板占位符（参数会静默错配）；在 `401` 上重试（连续十次认证失败会锁定凭证并逐步升级锁定）；双跑期间省略 `Idempotency-Key`（超时重试会发送两次）；用 profile 作用域 key 发送 `x-profile-id`（返回 `403`）；照搬 incumbent 的 `Authorization: Bearer` 模式（Sent 用 `x-api-key` 认证）。

适用边界 · 注意事项

• 不负责生成 Sent 客户端和韧性工作（交给 `sent-integration-starter`）、渠道语义（交给 `sent-routing-strategist`）、接收器构建（交给 `sent-webhook-engineer`）、WhatsApp 入驻（交给 `waba-embedded-signup`）和美国活动注册（交给 `sms-10dlc-registration`）。
• 不适用于没有 incumbent CPaaS 供应商需要替换、或不需要逐行迁移规划的场景。