旧系统通知链路迁移，先固定收件人与内容，再切换唯一发送主责

先按通知目的与送达责任选择迁移方式

适用边界：先定义通知目的、责任与不能承诺的结果

这份方法适用于更换邮件或短信供应商、把散落发送代码收口为通知服务，或在旧系统升级时统一多端消息。它不保证邮件一定进收件箱、短信一定到达终端，也不替代适用地区和行业的通信、隐私或营销合规判断。

先把通知分成身份安全、交易履约、服务提醒、内部告警和运营订阅等真实目的，写清触发事实、允许延迟、接收对象、失败后的业务动作与是否允许备用渠道。分类不能只看模板名称：同一“订单通知”可能包含履约必需信息，也可能夹带促销内容；是否需要同意、能否退订、保留多久，应由业务、法务或合规负责人结合地区、行业、渠道和实际内容确认。

邮件、短信、应用内消息、小程序订阅消息和 APP 推送的身份、模板审核、退订能力、状态含义与送达证据不同。本文只提供工程迁移框架，具体供应商能力以目标账号、地区、渠道和当前官方文档及联调结果为准。无法取得合法发送身份、有效联系人来源或旧退订记录时，应停止对应批次，不以更换供应商绕过缺失证据。

• 每类通知明确业务目的、触发事实、时效、失败处置和责任人。
• 交易与运营内容按真实用途评审，不用内部标签代替同意与合规判断。
• 把供应商受理、渠道送达与用户实际阅读视为不同证据层级。

从业务动作和供应商账单两端盘点全部发送入口

只搜索一个短信 SDK 会漏掉数据库任务、报表脚本、客服后台、云函数和供应商控制台群发；只看供应商记录又无法解释由哪个业务动作触发。盘点必须能从业务单据追到发送尝试，也能从供应商消息反查业务来源。

列出 Web、后台、小程序、APP、AI 智能体、定时任务、消息消费者、数据库过程、运维脚本与人工按钮中的发送入口；记录通知类型、触发条件、模板、收件人字段、发送账号、地区、日常峰值、超时、重试、回调地址和维护人。同步导出可用的供应商消息记录、模板清单、发送身份、域名配置、退信投诉、退订与抑制数据，按允许范围脱敏保存。对“代码里没找到但账单存在”的流量单独追责。

从代表业务单据抽样建立追踪链：businessEventId、notificationId、模板版本、收件人快照、创建时间、每次 attemptId、供应商消息 ID、回执事件与最终处置。特别检查联系人在业务发生后被修改的场景：若发货通知应发给下单时确认的号码，就不能执行时再读取客户资料中的最新地址；若安全通知必须发给当前绑定方式，则要明确读取时点。收件人选择规则必须由业务语义决定并可复现。

• 业务入口、任务脚本、人工控制台和供应商侧发送记录完成双向核对。
• 模板、账号、域名、密钥、回调、名单与抑制数据都有负责人和迁移去向。
• 代表消息可以从业务事实追到每次发送尝试，也能从供应商 ID 反查来源。

建立通知意图、模板版本和收件人快照三份稳定契约

旧系统常把“查用户、拼字符串、调用供应商”放在同一个请求里，失败后既不知道当时准备发什么，也无法安全重试。迁移时应先保存不可歧义的通知意图，再异步执行发送。

通知意图至少保存 notificationId、业务事件类型与唯一键、租户或组织、通知目的、渠道候选、收件人快照或受控引用、模板版本、变量快照、语言与时区、创建原因、最早发送时间、过期时间和当前状态。业务事件与通知类型建立唯一约束，同一订单状态重复到达时返回已有 notificationId，而不是创建第二条消息。个人信息只保存履约和审计所需范围，界面、日志与指标默认掩码。

模板不是随时覆盖的一段文本，而是有版本、变量契约、适用渠道、审批状态和生效区间的发布物。渲染前校验必填变量、长度、编码、链接域名和敏感内容，渲染后保存受控摘要或必要快照，使投诉、补发和审计能还原当时内容。旧模板与新模板先用脱敏样本比较主题、正文、金额、时间、姓名掩码、短链和退订入口；不能让 AI 在发送时自由改写交易数字、权限说明或已审批模板。

业务提交与发送供应商之间应有持久边界，例如同库通知意图、事务发件箱或经过验证的平台事务能力。网页请求成功只表示业务事实和通知意图已保存，不等待外部渠道最终送达。若旧系统无法一次完成解耦，可先用适配器接管现有调用，统一生成 notificationId、模板版本和尝试记录，再逐步移动触发逻辑。

• 同一业务事件和通知类型只产生一个稳定 notificationId。
• 模板版本、变量契约、审批与渲染证据可追溯，旧内容不被静默覆盖。
• 业务提交先于外部发送，供应商故障不会回滚已成立的订单或审批事实。

把发送尝试与业务通知分层，回执按证据而不是到达顺序收敛

一次通知可以有多次发送尝试，每次尝试又会经历本地排队、供应商受理、渠道发送、送达、延迟、退回或投诉等状态。状态必须表达实际证据，不能用一个布尔值混合全部阶段。

为每次外部调用创建 attemptId，保存 notificationId、渠道、供应商、发送账号、幂等依据、请求时间、响应类别、供应商消息 ID、结果未知原因和下一步。调用超时只说明本系统没有按时得到响应；先用同一幂等依据查询、等待回执或人工核查，不能立刻生成新身份重发。供应商返回成功通常只证明请求被接受或进入队列，页面应显示“已提交”“已送达”或“失败”等真实状态，不把受理冒充送达。

Twilio 官方资料说明出站消息会经历 queued、sent、delivered、failed、undelivered 等状态，并提醒状态回调受网络影响可能不按发送顺序到达。实现时对回调验签、解析允许字段扩展、按供应商事件或“消息 ID + 状态 + 时间”去重，并依据允许的状态图更新；迟到的 queued 不能覆盖已经确认的 delivered，重复 delivered 也不能再次触发业务奖励。Amazon SES 的事件模型同样区分 Send、Delivery、Bounce、Complaint、DeliveryDelay 和 Rendering Failure 等事实，且多种通知方式并用时可能收到同一事件的多份通知。

回调入口与业务查询分离，先持久化原始事件的必要字段和接收结果，再由可重放处理器更新尝试状态、联系人抑制和告警。验签失败、未知消息 ID、未知事件类型、时间异常和长期未决都进入隔离队列，不把未知字段当成成功。旧供应商回调地址在观察期保持可用，因为切换前已受理的消息可能在切换后才返回送达或退信。

• notificationId 表示业务通知，attemptId 表示一次渠道尝试，供应商消息 ID 只表示外部资源。
• 回调验签、去重、允许乱序与字段扩展，状态只按更强证据收敛。
• 结果未知、迟到回执和未知事件有隔离、查询与人工处置入口。

把退订、投诉、无效地址和业务禁发合并成发送前决策

迁移名单最危险的错误不是少导入一列，而是把曾经退订、投诉或已失效的联系人恢复为可发送。偏好与抑制记录应有来源、范围、时间和优先级，并在真正发送前再次判断。

为联系人和主题记录同意或订阅来源、适用目的、渠道、状态、时间、版本与证据；把用户退订、硬退信、投诉、无效号码、账户关闭、业务黑名单和人工禁发分别保存。不同记录可能只作用于某个主题，也可能禁止整个渠道，优先级和恢复条件必须显式。迁移采用旧、新系统抑制集合的保守并集开始，差异经业务与合规确认后再修正，不把缺失解释为同意。

Amazon SES 官方订阅管理可基于联系人列表与主题处理退订，并阻止随后向该联系人发送对应主题；但这属于特定产品能力，项目仍要验证发送请求是否带入正确列表和主题，也要处理其他入口。RFC 8058 定义了基于 HTTPS POST 的邮件一键退订机制以及 DKIM 覆盖相关头字段等要求；是否适用及如何配置应按邮件类型、发送域和接收方要求验证，不能只在正文放一个链接就宣称完全符合。

发送工作器在每次尝试前读取最新资格决定，记录决策版本和拒绝原因。退订或投诉处理必须幂等并尽快传播到所有发送入口；缓存需要明确失效时间。测试环境使用专用地址和供应商测试能力，不向生产联系人试发。收件地址、手机号、正文、签名链接与供应商密钥不进入普通日志、URL 参数或高基数指标。

• 退订、投诉、无效地址、账户状态和人工禁发按来源与作用范围保存。
• 旧新抑制名单先保守合并，差异有批准证据，缺失不自动视为允许。
• 每次发送前重新判断最新资格，测试流量与生产联系人严格隔离。

实施步骤：影子只比较不触达，再分范围转移唯一发送权

新旧链路同时真实发送不是安全的“双写”，而是直接制造重复通知。影子阶段只生成计划、渲染内容、路由与资格判断，真实发送仍由旧链路唯一负责。

第一步冻结入口、模板、名单与状态口径，给旧发送增加 notificationId 和供应商消息 ID 记录；第二步用历史脱敏样本和供应商测试号码验证新适配器；第三步生产影子运行，新链路读取同一通知意图但只写比较结果，不调用真实发送 API；第四步按低风险通知类型、内部租户或单一渠道切换，在路由表中把该范围设为新链路唯一主责，同时让旧入口对相同范围拒绝执行；第五步观察完整业务周期，再逐批扩大；第六步停止旧任务、撤销发送凭据并保留受控查询证据。

每个批次记录最后一个旧 notificationId、第一个新 notificationId、旧侧待发送和结果未知集合、模板与路由版本、回调积压、开始时间、观察窗口和回退负责人。回滚时只把尚未被任何供应商受理的新意图交回旧主责；已提交、状态未知或已经送达的尝试继续由原链路收敛，明确失败且业务仍有效时才按规则创建后续尝试。旧凭据在观察期最小权限保留用于查询或受控恢复，不继续开放给散落脚本。

多供应商容灾也遵守单次尝试主责。只有主通道明确失败、超过业务有效期策略或经查询确认未受理时，才按预设规则选择备用通道；切换原因写入尝试记录。验证码、付款、预约等有时间窗口的消息过期后不补发旧内容，应让用户重新发起并生成新的业务挑战或状态通知。

• 影子链路不调用真实发送接口，只比较收件人、模板、资格、路由和预计内容。
• 每个范围同一时刻只有一个发送主责，旧入口在切换后主动拒绝旁路。
• 回滚按未提交、已受理、结果未知、明确失败和已送达分别处理。

验收与风险：按通知事实、触达证据和用户偏好三条线对账

验收不能只看新供应商控制台的发送总数。要从应产生的业务通知、实际外部尝试、最终回执与不应发送的抑制样本分别证明没有漏发、重复、错发或越权。

准备覆盖正常、重复业务事件、模板缺变量、联系人修改、退订、投诉、无效地址、供应商超时、回调重复乱序、回调验签失败、过期消息、备用通道、切换中回滚和旧脚本恢复的样例。按 notificationId 核对应有通知数，按 attemptId 核对外部调用，按供应商消息 ID 核对回执，按联系人与主题核对允许和拒绝。邮件还要检查发送身份、域名认证、主题与正文、退订入口及退信投诉处理；短信检查签名、模板、编码分段、状态回执与号码格式，具体以供应商和地区实测为准。

容量验收使用测试目的地和受控速率，逐步验证队列积压、供应商限额、回调峰值、数据库连接、重试预算和告警，不用真实客户做压力测试。监控按渠道、通知类型、供应商和有限错误分类统计创建、抑制、提交、送达、延迟、退信、投诉、未知与过期；不把手机号、邮箱、notificationId 或自由错误文本放入指标标签。告警要能定位通知意图与尝试记录，但展示时继续脱敏。

主要风险包括旧脚本旁路、模板版本漂移、联系人快照错误、供应商结果未知后的重复改投、乱序回执覆盖终态、退订传播延迟、测试误发生产联系人、密钥和签名链接泄露，以及对“送达”含义做过度承诺。若业务必须证明本人知悉或法律送达，普通邮件短信回执通常不足以单独承担该责任，应由业务与专业负责人选择适合的确认机制。

• 应通知、已抑制、外部尝试、供应商回执和最终业务处置能够逐笔对账。
• 重复、乱序、超时、过期、备用通道、退订、旧脚本和回滚故障均完成演练。
• 监控标签有界且信息脱敏，送达证据和适用边界不被夸大。

需求讨论中的问题

关联服务与实施资料

下面的页面可继续核对相关技术边界、业务接入方式与项目交付条件。

• 旧系统消息队列迁移指南：继续处理通知意图的事件契约、持久发布、重复消费与切换水位。
• 旧系统定时任务迁移清单：盘点批量提醒、补发、名单同步和清理任务的单一执行主责。
• API 重试风暴与幂等指南：处理供应商超时、结果未知、退避预算与稳定幂等身份。
• 高基数监控指标治理指南：为通知类型、渠道和错误分类设计可控指标，避免联系人进入标签。
• AI Agent 智能体开发：让智能体通过授权工具创建可审计通知意图，而不是直接调用发送账号。
• 小程序与 APP 一体化开发：统一多端通知偏好、状态查询、深链和失败后的用户提示。
• 软件项目启动资料包：整理通知清单、模板、账号、名单、接口、责任人和验收样例。