企业微信 iPad 协议开发怎么落地

先把四个阶段和出口条件钉死

「企业微信 iPad 协议」这个说法本身不携带技术信息，它只表达一个诉求：让系统直接操作账号。所以落地的第一件事不是选技术栈，而是承认这是一个分阶段的工程，每个阶段有明确的出口条件，达不到就不往前走。

1. 1验证期（约两天）：出口条件是一张实测过的能力清单，上面写明哪些能力自己跑通过、哪些只在文档里见过。
2. 2接入期（一到两周）：出口条件是三个结构性决定已经写进代码，而不是写在会议纪要里。
3. 3灰度期（两到四周）：出口条件是第一批账号连续跑满一个完整周期，覆盖工作日高峰和周末低谷。
4. 4常态期：出口条件是有人负责、有告警、有回退动作，且回退动作被真实演练过至少一次。

这个划分挡住的是最常见的一种进度假象：接口调通了就宣布「已接入」，然后把剩下八成的工作压到上线之后。按出口条件走，每个阶段结束时你手上都有一个能给别人看的产物，而不是一句「差不多了」。

跳阶段的代价并不对称。验证期跳过去，问题会在灰度期以「这个能力其实不支持」的形式出现，返工的是架构；接入期跳过去，问题会在常态期以「加一个账号要改十处代码」的形式出现，返工的是全部调用点。前者贵在时间，后者贵在时机 —— 它总是发生在业务正要扩量的那一周。

验证期：两天，五件事自己动手做完

验证期要做的不是问对方能不能，而是自己跑一遍。这和向服务商提尽调问题是两回事：那些问题考察的是对方怎么答，下面五件事考察的是系统实际怎么反应，答得再漂亮也替代不了跑一遍。

1. 1成功路径：发一条消息出去，确认对端收到，记下端到端耗时。这一步顺利得让人放松警惕，所以它只算热身。
2. 2错误路径：故意造三种错 —— 参数不合法、目标不存在、短时间打满配额，看返回能不能把它们区分开。分不开，后面的重试策略就没法写。
3. 3事件链路：收到一次真实事件，确认从对方动作到你的服务落库这一段的时延，以及重复投递时你这边会不会出现两条记录。
4. 4第二个账号：换一个实例标识跑同一段代码。如果需要改代码而不只是换参数，说明多账号在这套接入形态里不是一等公民。
5. 5一次掉线：主动把账号退出登录，看状态多久反映出来、有没有告警、恢复要不要人参与。这一项直接决定你的值班安排。

第五项最容易被跳过，也最贵。账号可用性是这条路线唯一独有的风险，其余部分和对接任何 SaaS 没有区别。用 wecomapi 这类托管式接入时，实例状态在控制台是可见的，验证期就该把「状态从异常到可见」这段时延测出来 —— 它决定了你是先于客户还是后于客户知道出了事。

接入期：三个决定必须在写业务代码之前定死

接入期的技术含量不高，但它决定了半年后改一次需求要动几个文件。下面三个决定改起来的成本随时间陡峭上升，所以必须在第一周做完。

一、账号标识是显式参数，不是全局配置

第一天只有一个账号时，把它塞进全局配置或环境变量非常自然，省下的时间大概十分钟。代价是接第二个账号那天，所有调用点、所有日志、所有限流桶都要改一遍。正确做法是从第一行代码起，账号实例标识就作为显式参数一路传到底：日志按它分组，限流按它分桶，重试记录按它归档。

// 示意结构。精确字段与错误分类以 wecomapi 文档为准

async function sendText(guid, toId, content, traceId) {
  // guid 是账号实例标识：日志、限流桶、重试记录都按它分组
  return http.post("/message/sendText", { guid, toId, content }, {
    timeoutMs: 8000,
  });
}

// 反例：把当前账号藏进全局状态
// setGlobalInstance(...)   ← 第一天省十分钟，第三个月还两周

二、入站事件只有一个入口

现在你可能只有一个事件来源，但补偿拉取、历史导入、人工重放这些迟早会出现。提前把它们收敛成同一个入口函数，成本是十行代码；等三个来源各写了一套处理逻辑再合并，成本是一次带线上数据的重构，而且合并期间的幂等行为几乎必然出错。

三、给「发出去了」定一组状态，别只记成功失败

接口返回成功不等于对方收到，超时也不等于失败。数据模型里至少要有四个状态：待发、已提交、已确认、已放弃 —— 这套口径站内讲消息接口那篇有完整定义，这里只强调对这条路线最要命的一档：超时和响应丢失只能停在「已提交未确认」，不能落成失败。一旦落成失败，补发逻辑就会在下游其实已经成功的情况下再发一次，客户收到两条一模一样的消息。这个坑的特点是联调期完全遇不到，放量当天集中出现。

这组状态还有一个附带要求：幂等键必须由你生成并原样透传，不能等对方返回之后再拿返回里的标识做键。理由很直接 —— 超时的那次调用根本没有返回，而「已提交未确认」偏偏就是从超时来的，用返回值做幂等键，恰好在最需要幂等的那一类场景里失效。

状态定下来之后，补发就有了明确规则：已确认不补，已提交未确认的按幂等键重试，超过时效窗口或重试用尽转已放弃。先用 wecomapi 的错误分类把可重试和不可重试切开，剩下的模糊地带才是需要这套状态兜住的部分 —— 这两件事顺序不能反，先分类再定态，否则你会把明确的失败也塞进未确认那一档，补发量凭空翻几倍。

灰度期：按账号放，不按流量放

按流量百分比灰度是 Web 服务的默认做法，搬到这条链路上是错的。故障单位不是请求，是账号：一个账号出问题，它名下所有会话一起出问题。按 5% 流量灰度，结果是每个账号都承担 5% 的风险；按账号灰度，才是让 5% 的账号承担全部风险，其余账号完全不受影响。只有后者算灰度。

1. 1第一批放一到两个账号，跑满一个完整周期。周末和夜间必须覆盖，有些问题只在长时间空闲之后才出现。
2. 2第二批扩到一条完整业务线，盯三个数：发送失败率、事件端到端时延、账号在线时长占比。任意一个出现趋势性恶化就停。
3. 3第三批再全量。全量之前把回退动作写成一页纸的操作步骤交给值班的人，而不是留在实施同学脑子里。

按账号灰度带来一个附加要求：监控也得按账号看。全局平均值会把单账号的异常稀释掉 —— 十个账号里有一个完全不工作，整体失败率只有 10%，看起来像抖动，实际上是一批客户彻底失联。灰度期的看板至少要能按账号下钻，而这个看板在常态期同样有用，不算额外投入。

回退方案必须是「把这批账号切回人工」，不能是「关掉系统」。客户正在对话的时候关系统，比不上线还糟。这意味着人工兜底的入口在灰度期就要保持可用，而不是等到需要时再临时恢复 —— 临时恢复的那十分钟，正好是客户体验最差的十分钟。

边界：这条路线不会给你的三样东西

落地前把预期对齐，比落地后解释便宜。下面三样是需求方最常默认存在、实际不存在的东西。

• 历史不会凭空出现。接入那一刻是起点，之前的会话不会补进来。任何依赖历史数据的分析需求，排期都要从接入日开始算，而不是从公司成立那天。
• 速率上限不会变。换一种接入方式不会改变平台侧的行为约束，批量任务照样要打散、要退避、要分时段。按「接进来就能发得更快」排期，第一次放量就会撞墙。
• 人不会完全退出。登录需要真人参与，账号异常需要人处理，运营规则需要人调。自动化能把人力从每天几小时压到每周一小时，但压不到零，值班表得提前排。

预期对齐要落到验收标准上，口头讲过不算数。可操作的写法是把三条各写成一句可判定的话：历史数据从接入日算起、批量任务分时段执行且有速率上限、账号异常由某个角色在多长时间内响应。写不进验收标准的预期，最后一定会以争议的形式回来。三条里第三条最容易被当成软性目标一带而过，但它恰恰是唯一需要落到排班表上的一条 —— 没有具体的人和具体的响应时间，这条就等于没写。

这三条讲清楚之后，项目的成功标准会变得诚实很多：不是「全自动」，而是「人只在必要的地方出现」。按这个标准验收，双方都不会在最后一周吵架。