migrate-to-sent

迁移到 Sent

从主流 CPaaS 提供商迁移时，总会遇到相同的五个转换问题。请按以下顺序处理，因为第一个问题会悄悄让成本翻倍，而且测试中无法发现。

1. 有序回退变为自动路由

现有平台通过不同的调用方数组、故障转移对象、消息服务功能或应用级优先级配置来实现跨渠道投递。不要假设这些结构在 Sent 请求字段中有直接对应项。

Sent 的 channel 数组是广播列表。 移植有序数组会为每个收件人和渠道组合发送一条消息并收费一次；这样虽能通过测试，却会让生产费用成倍增加。正确的转换方式是使用自动路由——省略 channel 或发送 ["sent"]——这样平台便能选择路由，并在同一个 message_id 上跨最多三个渠道和提供商组合重新路由。详情请参阅 sent-routing-strategist；迁移规则很简单：切勿移植有序渠道列表。

2. 状态词汇并不匹配

现有状态可以映射到 Sent 的状态，但 Sent 还新增了两个没有对应状态、会破坏简单重试逻辑的状态。

Sent 状态	最接近的现有状态	迁移说明
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	无对应项	在免打扰时段暂停；之后会自动恢复

移植代码时有两个影响。将所有非已送达终止状态都视为可重试的处理程序会重试同意状态拦截，这属于合规问题，而非程序错误。另外，依赖提供商数字错误代码的处理程序——Twilio 的 21610 就是典型例子——必须改为根据 Sent 的字符串 error.code 分类来处理。

3. Webhook 验证需要重写，而非移植

没有两家提供商使用相同的签名方式，而且没有任何 Sent SDK 内置验证器。

提供商	方案
Twilio	X-Twilio-Signature：对完整 URL 和排序后的 POST 参数计算 base64 HMAC-SHA1
Sinch	对 body.nonce.timestamp 计算 HMAC-SHA256；使用四个 x-sinch-webhook-signature* 请求头；或使用 OAuth 2.0
Infobip	Basic、对原始请求体计算 HMAC-SHA256，或在通知配置文件上使用 OAuth；请求头名称由账户配置
Vonage	Authorization: Bearer 中的 JWT，或旧版 sig 参数
MessageBird/Bird	messagebird-signature：对时间戳、URL 和 SHA-256 请求体哈希计算 base64 HMAC-SHA256
Sent	x-webhook-signature: v1,{base64}：对 {x-webhook-id}.{x-webhook-timestamp}.{raw_body} 计算 HMAC-SHA256

Sent 的密钥是去掉 whsec_ 前缀后再进行 base64 解码的签名密钥；比较时采用恒定时间算法，并拒绝时间戳偏差超过 300 秒的请求。由于 Sent 不提供事件级 ID，去重键必须根据载荷语义生成。请使用 sent-webhook-engineer 构建接收器，而不是改造现有提供商的验证器。

4. 退出订阅列表必须协调，而非直接复制迁移

每个服务提供商都会维护自己的屏蔽列表——Twilio Advanced Opt-Out、Infobip Blocklist、Sinch OPT_IN/OPT_OUT 事件。Sent 会在事件到达应用之前，于平台层面强制执行同意规则，将其存储为联系人上的 opt_out，并且不区分渠道地应用：在 SMS 上回复 STOP，也会屏蔽 WhatsApp 和 RCS。

协调规则：切换前导出现有服务提供商的屏蔽列表，将现有服务提供商任意渠道上的退出订阅记录都视为全局 Sent 退出订阅，并且绝不要为了“清理”迁移数据而清除 opt_out。Sent 的 10 个默认关键词为 STOP、CANCEL、UNSUBSCRIBE、QUIT、END、START、UNSTOP、SUBSCRIBE、HELP、INFO，仅当去除首尾空白后的完整消息正文与关键词完全相等时才会匹配——因此，现有服务提供商的专用关键词需要自定义关键词条目。将现有服务提供商的任何关键词匹配器改写为精确的本地同意状态镜像和审计机制；匹配器不得再次向 Sent 写入同意状态。同意语义由 sent-two-way-messaging 负责。

5. 模板和租户配置需要重新注册，而非转移

WhatsApp 模板归 WABA 所有，因此迁移时需要确定的是 WABA 是否会转移。Sent 使用命名参数替代位置占位符（{{1}}、{{2}}），这意味着所有传入有序数组的调用点都必须改为传入命名映射。审批是异步进行的，审批结果会通过 templates webhook 事件送达，因此应在切换前而非切换期间建立模板清单。

租户配置的映射如下，边界决策由 sender-profile-architect 负责，API 工作由 sent-profile-provisioning 负责：

现有服务提供商构造	Sent 对应项
Twilio 子账户	Sender Profile
Twilio Messaging Service	路由加 Profile 配置，而非调用方一侧的池
Infobip Application 或 Entity	Sender Profile
Sinch Conversation API app	Sender Profile
每个租户各自的服务提供商 API 凭据	Profile 级 API 密钥，或带有 x-profile-id 的组织密钥

迁移步骤

1. 清点每个发送调用点、webhook 处理程序、状态分支、模板、屏蔽列表和凭据。使用 scripts/inventory_scan.py 以程序方式查找。该脚本会读取所选仓库中的本地常规文件，跳过符号链接和环境文件，并报告路径、行号及迁移指导，但不提供源代码摘录。该脚本不会发起网络请求。
2. 映射每项内容，参照 references/provider-mapping.md，并将有序回退数组和数字错误代码标记为必须改写的内容。
3. 并行部署 Sent：配置凭据和每个环境各一个 webhook，验证接收方，并重新注册和审批模板。
4. 在沙盒中验证等效性：设置 "sandbox": true，随后使用确认状态为 DELIVERED 的小规模实时群组进行验证。
5. 双路运行并拆分流量，针对相同消息类别比较送达率、延迟和每条消息的成本。
6. 按消息类别切换——先切换风险最低的事务类消息，最后切换营销消息——同时保持现有接收方在线。
7. 停用现有服务提供商：只有在完整计费周期内数据正常后才能停用，然后撤销其凭据。

切换顺序详情、验证关卡和回滚触发条件请参阅 references/cutover-playbook.md。

测试未能发现的问题

• 移植有序渠道数组。成本翻倍，且不会报错。
• 将 FILTERED 视为可重试。会带来合规风险。
• 重用现有服务商的签名验证器。每次投递都会返回 401。
• 认为 202 表示已投递。Sent 仅确认已接受请求。
• 保留位置型模板占位符。参数会悄然错配。
• 遇到 401 时重试。连续 10 次身份验证失败会锁定凭据，且锁定时长会逐步增加。
• 双重运行期间省略 Idempotency-Key。超时后重试会导致重复发送。
• 使用与配置文件关联的密钥时发送 x-profile-id。会返回 403。
• 照搬现有服务商的 Authorization: Bearer 模式。Sent 使用 x-api-key 进行身份验证。

职责边界

本技能负责服务商映射和逐行迁移规划。将生成的 Sent 客户端及弹性处理工作交给 sent-integration-starter，将渠道语义交给 sent-routing-strategist，将接收器构建交给 sent-webhook-engineer，将 WhatsApp 入驻交给 waba-embedded-signup，并将美国营销活动注册交给 sms-10dlc-registration。