企业微信自动化接口全景

先按驱动源分，别按能力域分

按消息、客户、群、事件回调这样的能力域分类，是文档的组织方式 —— 对查字段的人有用，对设计自动化的人不够用。能力域回答的是「有没有这个接口」，而线上出问题时你要回答的从来是另一个问题：这个动作由谁在什么时候拉起来，它到底有没有被拉起来过。

按后一个标准切，企微自动化里能被自动化的环节只有四种驱动源，每一种都有固定的软肋。

• 平台事件：企业微信侧发生了什么（有人发消息、有人加好友、群成员变了），事件推到你的服务，你决定做什么。时延最低，软肋是触发时机和峰值都不由你决定，流量形状是别人给的。
• 时钟：到点就跑（每日播报、超期跟进、状态对账）。时机完全可控，软肋是时延等于调度周期，而且失败最安静 —— 一个任务没跑起来，不会有任何人收到通知。
• 上游调用：你自己的系统发生了什么（订单发货、工单升级、审批通过），由它调用自动化服务。上下文最全、时延低，软肋是量由上游决定，上游一次批处理就能把你压垮。
• 人工确认：机器把动作准备好，人点一下才执行。慢，但它是唯一能把判断留在人这边的形态。

驱动源选错的症状是固定的两种。该用事件的用了时钟，表现为「客户发完消息五分钟才收到回复」，这是体验问题；该走人工确认的做成了全自动，表现为某天早上发现一批消息发给了不该发的人、而且已经发完了，这是事故。两者的修复成本差着量级，所以这个选择要在写代码之前定，不是写完再补。

还有一种选错的方式更隐蔽：同一个动作被两类驱动同时拉起来。事件触发发了一次欢迎语，晚上的补偿任务发现「这个客户没有欢迎语记录」又发了一次 —— 因为记录写失败了，动作本身是成功的。补偿任务的正确写法永远是「查缺再补」，且查的必须是外部实际状态，不是自己的执行记录。

「什么都没发生」不会有事件，只能自己合成

事件回调只推「发生了什么」，它推不出「什么都没发生」。客户三天没回消息、券领了一直没用、群里一周没人说话 —— 这些条件在事件流里没有任何对应的输入，而它们恰恰占了自动跟进类需求的大头。这是全景图上最容易被漏掉的一块：不是接口不支持，是这类触发天生不存在。

所以缺席型触发必须自己造：用事件流维护一份「最后一次活动时间」，再由时钟扫描把「超过阈值」翻译成一个内部事件，交给和其他驱动源同一套动作层。做法上，用 wecomapi 的事件回调把消息、入群、客户变更这些落成带时间戳的活动记录，扫描只读自己的库，不要为了判断「有没有发生」反复去拉平台。

• 扫描周期就是这类自动化的精度上限。五分钟扫一次，就别对业务承诺「三天整点触发」。
• 阈值判断要基于活动记录本身，不要基于「我上次扫到哪」。前者随时可重算，后者一旦游标丢了就再也补不回来。
• 停机之后必须有静默期。停两个小时，恢复时一大批实例的阈值会同时过线、一起触发 —— 这是缺席型自动化最典型的一种事故形态。

静默期的做法很土但有效：恢复后先只记录不执行，跑满一个扫描周期，把「本该在停机期间触发」的那批单独标出来，由人决定补发还是丢弃。无脑全量补发几乎总是错的 —— 这类动作大多是有时效的提醒，隔两小时再发只会让收件人困惑。

触达类和状态类，失败方式是镜像的

四种驱动源之下，被驱动的动作只有两类：触达类（消息发出去了、群建起来了，对方能感知）和状态类（标签打上了、备注改了、客户转给了谁，只体现在数据里）。这两类的失败方向正好相反，防护手段不能共用一套。

触达类的失败是显性的：多发一条客户会说，少发一条业务会问。它需要的是幂等，而且幂等键要落在真正产生外部动作的那次调用上，不是落在事件入口 —— 这部分站内另有专文，这里不展开。

状态类的失败是隐性的：一次打标签没成功，没有任何人会发现，直到三个月后有人问「这批客户为什么一直没进跟进序列」。它需要的不是幂等，是对账。用 wecomapi 的客户与标签读接口按批次把当前状态读回来，和本地期望值 diff，只报差异、不自动修复 —— 自动修复在真出故障时会拿一份错误的期望值把全库刷一遍，那种事故比漏打几个标签贵得多。

• 触达类的监控指标是重复率和失败率，看的是「有没有发多」。
• 状态类的监控指标是差异条数，看的是「漏了多少」，而且这个数得有人每天真的看一眼。
• 两类都要一个可回溯的调用标识：从一条业务记录能反查到那次请求，从那次请求能反查到触发它的事件。

四种驱动收敛到同一个执行层

真实链路很少只有一种驱动。新客进来之后的自动跟进：加好友事件触发 → 打来源标签 → 发欢迎语 → 三天没回复则提醒（时钟合成的缺席事件）→ 客户在 CRM 里被标为高意向时推一条内部通知（上游调用）→ 要发促单话术时进人工确认队列。四类全用上了，而它们必须共用同一个动作执行层。

// 示意结构，只表达分层关系；精确字段、事件类型与端点以线上文档为准
const triggers = {
  event:    onWecomEvent,      // 平台事件回调
  schedule: onCron,            // 时钟，含缺席型的合成事件
  system:   onInternalCall,    // 上游系统主动调用
  manual:   onOperatorConfirm, // 人工在后台点了确认
};

// 四类触发最后只进这一个口子，限流 / 去重 / 留痕都收在这层
async function execute(action) {
  if (await sent.has(action.key)) return;      // 发送记录兜底，防重复
  await limiter.acquire(action.accountId, {    // 限流按账号维度，不按全局
    deferrable: action.deferrable,             // 唯一值得从触发源带下来的元数据
  });

  const res = await http.post("https://manager.wecomapi.com/message/sendText", {
    guid:    action.accountId,
    toId:    action.to,
    content: action.text,
  });

  await sent.record(action.key, res);          // 留痕，供对账与反查
  return res;
}

执行层不该知道自己被谁触发。一旦里面出现按触发源分支的判断，四类驱动就重新粘回去了，之后每加一个触发源都要改这个函数 —— 而它是全链路唯一的收敛点，改它的风险最高。触发源之间的差异应该在进入执行层之前就被抹平成同一个动作描述。

人工确认那一路要特别注意接法：人点确认之前，动作就应该已经是一个完整的对象躺在队列里，人只是给它一个执行许可，而不是在确认界面上重新拼一次参数。界面上拼参数意味着人工那一路绕过了前面所有的校验和限流，它会成为唯一一条没有防护的路径，而且通常是在最忙的时候被用到。

唯一值得一路传下来的元数据是「能不能被延后」。实时应答不能延，批量播报能延；执行层被限流挡住时，靠这一个标记就能决定是排队还是直接拒绝，而不是让所有动作一起变慢。让所有动作一起变慢的坏处在于，它不会触发任何告警。

接入顺序与三个常见错法

1. 1先接平台事件那一路，哪怕只订阅一种事件。它是唯一能让你看见「系统里正在发生什么」的通道，没有它，后面所有自动化都是盲跑。
2. 2再补执行层，把限流、重试、发送记录一次做齐。这一层只写一次，越早写省得越多。
3. 3最后才做时钟与人工确认。它们依赖前两步的产物 —— 活动记录和动作定义，提前做必然返工。

第一个常见错法：把定时轮询当成事件驱动的替代品。「每分钟拉一次新消息」在量小的时候确实能跑，量上来之后它同时贡献了时延和大量无效调用。注意它和上面说的缺席型扫描不是一回事 —— 那个扫的是自己的库，这个是在反复问平台「有没有新东西」。

第二个：给每个自动化环节各写一套重试。重试逻辑散在十个地方，等到某天需要把某类动作整体降级，你会发现没有一个统一的开关可以拧。

第三个：把人工确认做成审批流的样子。确认环节的价值在于快 —— 一个列表、一个按钮、支持批量勾选。超过两次点击就没人用，最后所有人绕过它手工操作，那条本来想保住的可控性反而丢了。