官网友情链接 wecomapi.com
企业微信二次开发系统运行时间越长，越会遇到一个无法回避的问题：
回调处理会失败。
客户新增事件可能失败；
群成员变化可能失败；
标签变化可能失败；
消息处理可能失败；
外部群变化可能失败。
很多系统一开始的方案是：
失败以后自动重试。
但当重试次数用完以后怎么办？
如果只是写一条日志，然后等待技术人员人工排查，那么这些失败事件很可能长期遗留，最终造成数据不一致。
所以企业微信二次开发API 和企微开发API 真正进入生产环境以后，需要一个非常重要的能力：
事件重放。
WeComApi 可以作为企微API 接入层，把客户、外部群、标签和消息相关事件接入业务系统。本地系统则需要把原始事件保存下来，让失败事件未来可以重新处理。
一、为什么原始事件一定要先保存
如果回调进入以后直接做业务逻辑：
更新客户；
创建工单；
同步 CRM。
中间一旦失败，而原始事件没有保存，后续就失去了重新处理的依据。
更合理的方式是：
第一步：
保存原始事件。
第二步：
快速返回。
第三步：
异步处理。
这样即使业务处理失败，原始事件仍然存在。
二、原始事件应该保存什么
至少包括：
event_id；
event_type；
receive_time；
occurred_at；
原始 payload；
企业；
账号；
关联对象；
处理状态；
重试次数；
最后错误；
trace_id。
这些字段能帮助系统后续重新执行。
三、事件状态机怎么设计
可以有：
待处理；
处理中；
成功；
失败；
等待重试；
重试中；
待人工；
已忽略；
已重放成功。
这样事件从进入到结束有完整生命周期。
四、重试和重放有什么区别
重试：
通常是系统自动发生。
比如网络超时，1 分钟后再次执行。
重放：
通常是针对已经失败或历史事件，重新触发完整处理。
重放可能发生在：
修复 Bug 以后；
外部系统恢复以后；
管理员人工操作；
批量数据补偿。
两者应该分开记录。
五、一个具体例子
客户 A 在 10:00 新增。
事件 E1001 进入系统。
客户同步任务开始。
调用 CRM 时失败。
系统自动重试三次，仍然失败。
状态：
待人工。
下午 CRM 恢复。
管理员在异常中心点击：
“重新处理。”
系统不需要客户重新添加。
直接基于 E1001 重放。
重新执行：
客户识别；
CRM 写入；
标签初始化。
最终成功。
这就是事件重放。
六、重放必须幂等
这是最重要的地方。
如果原事件其实已经执行了一半：
客户已经创建；
标签还没成功。
重放时不能再次创建一个客户。
所以每个业务步骤都需要幂等。
例如：
客户创建检查 source_event_id。
CRM 写入检查业务唯一键。
标签操作检查当前状态。
这样重放只补缺失步骤。
七、重放不能简单从第一步无脑执行
更好的任务设计是步骤化。
比如事件 E1001 有：
步骤 1：客户关系同步，成功。
步骤 2：CRM 写入，失败。
步骤 3：标签初始化，未执行。
重放时可以从步骤 2 开始。
这样避免重复动作。
八、批量重放也需要限流
假设系统因为 Bug 积压了 10 万条失败事件。
修复以后，如果点击全部重放，瞬间会产生巨大压力。
所以需要：
批次；
并发限制；
优先级；
分片。
例如每分钟处理固定数量。
高优先级客户先处理。
九、历史 Bug 修复后特别需要重放
举个例子。
某段时间由于代码问题，客户标签没有正确同步。
修复以后，不能要求所有客户重新触发事件。
可以找到那段时间的历史事件，再重新执行标签步骤。
这就是保留原始事件的长期价值。
十、回调 Schema 变化也要考虑
未来事件结构可能变化。
所以保存原始 payload 的同时，也可以记录：
schema_version。
重放老事件时，使用对应版本解析器。
否则新版代码可能无法正确读取历史事件。
十一、事件重放需要权限
不是所有人都能重放。
普通运营可以处理普通业务异常。
技术管理员可以重放接口事件。
大批量重放最好需要更高权限。
因为重放可能影响大量客户数据。
十二、重放前要展示影响范围
批量操作前可以显示：
事件数量；
涉及客户；
涉及群；
事件时间范围；
预计任务数。
这样管理员知道自己将执行什么。
十三、重放也要有审计日志
记录：
谁发起；
什么时间；
哪些事件；
重放原因；
执行结果；
成功多少；
失败多少。
不能让大规模补偿成为无痕操作。
十四、WeComApi 在事件链路中的位置
WeComApi 负责：
企微开发API 接入；
客户事件；
外部群事件；
标签；
消息。
业务系统负责：
事件落库；
任务消费；
自动重试；
重放；
幂等；
异常中心；
审计。
WeComApi 负责让事件进入。
本地系统负责让失败事件“永远有机会被修复”。
十五、对账发现差异后也可以生成补偿事件
定期对账时发现：
远端有客户，本地没有。
可以生成一个人工补偿事件。
它虽然不是原始实时回调，但进入统一事件系统。
这样实时回调和对账补偿使用同一套处理链。
架构更统一。
十六、异常中心和事件重放应该连接
异常详情可以直接看到：
原始事件；
处理步骤；
最后错误；
已重试次数。
然后提供：
单条重放；
批量重放；
忽略。
这样技术和业务人员处理效率更高。
十七、为什么事件重放是生产级系统能力
Demo 系统关注：
成功路径。
生产系统必须关注：
失败以后怎么恢复。
如果一次失败就永久丢失，系统运行几个月以后，数据差异一定越来越多。
事件重放就是给系统一个“重新纠正历史”的机会。
十八、总结
企业微信二次开发API 和企微开发API 真正进入生产环境以后，不能只考虑“回调能不能收到”。
还要考虑：
收到以后失败怎么办。
WeComApi 可以作为企微API 接入层，把客户、外部群、标签和消息事件稳定送入业务系统。
但业务系统必须进一步建立：
原始事件；
状态机；
自动重试；
步骤化任务；
幂等；
批量重放；
权限；
审计。
一个成熟的企业微信自动化系统，并不是从不失败。
而是任何重要事件失败以后，都不会永久消失。
只要原始事件还在，处理逻辑可重放，系统就具备真正的恢复能力。
