研发平台对接企业微信前，需要把五类信息准备齐：两端系统与数据方向、企业微信侧的接入主体与权限、研发平台侧的账号与网络条件、字段与消息映射、运行保障与验收方法。本文按接入准备顺序给出可填写的清单和表格，覆盖企业应用连接范围；通讯录目录认证与日常沟通规范不在本文展开。
要点总览（TL;DR）
- 对接前先画清两端分工：研发平台生产事件，企业微信负责触达，并标注每个业务对象是单向推送还是双向回传。
- 企业微信侧要提前落实企业ID、自建应用或群机器人、应用Secret、可信IP、可见范围和通讯录读取权限，并指定凭据保管人。
- 研发平台侧要确认管理员账号与集成入口、回调地址、出口IP与代理放行，凭据放入配置中心并约定轮换步骤。
- 字段映射以研发平台账号与企业微信UserID的对照表为基础，消息固定包含标题、状态、负责人、时间和跳转链接。
- 联调覆盖正常推送、字段缺失、凭据失效和重复事件四类用例，并留存消息截图、返回码、日志和失败队列作为验收证据。
先确定两端系统与数据流向
动手配置前，先用一张表把连接关系画清楚：研发平台是消息的生产方，负责在业务对象发生变化时生成事件；企业微信是接收与触达通道，负责把消息送到指定的人或群。两端的分工确定后，后续申请凭据、设计字段、约定重试才有依据。
数据方向分两类，准备材料差别明显。单向推送只需研发平台能调用企业微信接口，准备重点是研发平台的出口网络和企业微信的应用凭据；双向回传还需要企业微信侧能回调研发平台，准备重点增加回调地址、公网可达性和回调验签材料。建议在方案里明确标注每个业务对象属于哪一类，避免联调时才发现回调地址没有登记。
纳入对接的业务对象要提前圈定。常见范围包括项目立项与结项、任务状态变更、缺陷指派与关闭、发布上线通知、文档评审提醒。范围越大，字段映射表和联调用例越多，建议首期选两到三类高频对象，跑通后再扩展。
| 数据对象 | 方向 | 触发时机 | 接收对象 |
|---|---|---|---|
| 任务状态变更 | 研发平台→企业微信 | 状态字段更新后 | 任务负责人、关注人 |
| 缺陷指派 | 研发平台→企业微信 | 指派人和处理人变化时 | 被指派人 |
| 发布上线通知 | 研发平台→企业微信 | 发布单进入已上线状态 | 项目群 |
| 文档评审提醒 | 研发平台→企业微信 | 评审发起或临近截止 | 评审人 |
| 消息已读或处理回执 | 企业微信→研发平台 | 用户点击卡片按钮 | 研发平台对应工作项 |
需要区分的是，企业微信通讯录与研发平台账号的目录认证同步属于企业身份与账号集成方向，团队日常沟通的消息礼仪属于团队沟通与信息同步方向。本文只处理应用之间的消息连接，把这两块排除在外，可以让准备清单更聚焦。
企业微信侧需要准备的主体与权限
企业微信管理后台的准备事项由企业微信管理员落实，研发团队需要提前列出清单并约定配合时间。核心是三样：接入主体是谁、权限范围多大、凭据由谁保管。
企业ID（CorpID）是企业的唯一标识，在企业微信管理后台的“我的企业”信息中可以查看，调用接口和拼接授权链接都会用到。自建应用与群机器人是两种常见接入形态：自建应用适合按人推送、需要读取通讯录和成员 UserID 的场景，能配置可见范围和应用菜单；群机器人适合把通知发到固定群聊，配置简单，但接收对象是群而非个人，也不具备通讯录读取能力。选择哪种形态，取决于第一步确定的数据对象和接收对象。
应用可见范围决定哪些成员能收到消息、能在工作台看到应用入口。范围过窄会漏发，过宽会带来无关打扰，建议按项目或部门划定，并在上线前复核。通讯录读取权限用于把研发平台账号映射到企业微信 UserID，需要在管理后台申请并由管理员审批，审批周期要计入排期。
可信IP和应用Secret属于敏感凭据。可信IP是调用接口的来源地址白名单，需要研发平台出口 IP 提前登记；应用Secret在自建应用详情页生成，只展示有限次数，应由指定责任人保管，通过密码管理工具交接，避免在聊天记录或文档正文中明文传递。
| 准备项 | 用途 | 获取路径 | 责任人 |
|---|---|---|---|
| 企业ID（CorpID） | 标识企业身份，接口调用与授权链接使用 | 管理后台“我的企业” | 企业微信管理员 |
| 自建应用或群机器人 | 确定消息触达形态 | 管理后台“应用管理” | 企业微信管理员 |
| 应用Secret | 获取接口调用凭证 | 自建应用详情页 | 集成负责人保管 |
| 可信IP | 限制接口调用来源 | 自建应用配置页 | 运维与管理员共同确认 |
| 应用可见范围 | 控制可接收消息的成员 | 自建应用配置页 | 业务负责人确认 |
| 通讯录读取权限 | 读取成员 UserID 用于接收人映射 | 管理后台权限申请 | 企业微信管理员审批 |
需要企业微信管理员配合的事项建议一次性列清：开通自建应用、配置可见范围、审批通讯录权限、登记可信IP、提供企业ID、确认Secret交接方式。把这些事项写进排期表，比在联调阶段临时找人更可控。
研发平台侧的接入前提与账号准备
研发平台一侧要先确认三件事：有没有配置入口、有没有足够权限、网络能不能通。三者缺一，后面的字段设计和联调都无法开始。
配置入口通常由研发平台的管理员在系统设置或集成配置中操作，需要确认当前账号具备管理员或集成管理权限，并明确由谁执行配置、由谁复核。若研发平台提供开放 API，还需要确认接口的鉴权方式、调用频率限制和可用的业务对象接口，这些信息以对应产品的开发者文档为准。
回调地址或 Webhook 地址用于双向回传场景。研发平台需要能生成一个可被企业微信访问的地址，并完成登记和验签配置。该地址要求公网可达、使用 HTTPS，并在企业微信侧完成域名或地址的配置。只做单向推送时，这一步可以简化，但仍需确认研发平台能主动发起外部请求。
网络条件容易被忽略。研发平台所在网络需要允许访问企业微信接口域名，出口 IP 要与登记的可信 IP 一致；若经过代理，代理的转发规则和超时设置要一并确认。私有部署环境下，出口网络往往由运维统一管理，建议提前申请放行并记录变更单号。
- 确认管理员账号与集成配置入口，记录操作人和复核人。
- 确认研发平台开放接口的鉴权方式与调用频率限制。
- 生成并登记回调地址，完成 HTTPS 与验签配置。
- 核对出口 IP 与可信 IP 一致，确认代理和防火墙放行规则。
- 确定凭据在研发平台侧的存放位置，约定轮换周期和轮换时的切换步骤。
凭据存放建议使用配置中心或密钥管理服务，避免硬编码在脚本里。轮换安排要与 Secret 的重置操作对齐：先在新旧凭据并存期内完成切换，再停用旧凭据，防止轮换瞬间消息中断。
字段映射与消息内容设计
字段映射是联调返工最多的地方，提前把源字段、目标字段和转换规则定下来，可以显著减少来回修改。映射表至少包含四列：源字段、目标字段、转换规则、示例值。
接收人映射优先使用稳定唯一标识。研发平台账号与企业微信 UserID 建立对照表，通过通讯录接口或管理员导出的成员列表批量匹配，避免用姓名或昵称匹配，因为重名和改名都会导致错发。对照表要保留更新机制，新成员入职时同步补充。
消息类型按场景选择。文本卡片适合需要标题、摘要和跳转按钮的通知，比如任务指派和缺陷提醒；Markdown 消息适合结构化展示多条字段，但要注意企业微信对 Markdown 语法的支持范围；图文消息适合带封面和摘要的发布公告。选择时以接收端能否清晰阅读为准，不必追求样式复杂。
| 源字段 | 目标字段 | 转换规则 | 示例值 |
|---|---|---|---|
| 工作项标题 | 卡片标题 | 超过 40 字截断并加省略号 | 登录模块接口联调 |
| 状态 | 状态描述 | 按状态字典转中文 | 进行中 |
| 负责人账号 | 接收人 UserID | 查对照表转换，缺失时转告项目负责人 | zhangsan |
| 更新时间 | 时间字段 | 统一为北京时间，精确到分钟 | 2024-06-12 15:30 |
| 工作项链接 | 跳转地址 | 拼接固定域名，携带工作项 ID | 研发平台工作项详情页 |
消息必含字段建议固定为标题、状态、负责人、时间、跳转链接五项，缺一项都会影响接收人判断是否需要处理。跳转链接的域名要与企业微信侧配置的可信域名一致，若研发平台要求登录后访问，需要评估免登方案，否则用户点击后停在登录页，通知的实际作用会打折扣。
字段缺失和超长要有明确规则：缺失字段用“未填写”占位，不直接留空导致卡片错位；超长文本按字符数截断并在末尾保留省略号，完整内容通过跳转链接查看。这些规则写进映射表，联调时逐条核对。
在研发平台一侧，工作项状态变化触发通知是常见的落地场景。以 ONES 为例，其资料说明支持一键对接企业微信等第三方应用，并提供 API 接口用于与企业系统集成；具体可推送的业务对象范围、消息类型和配置入口，需要在实施前查阅对应版本的开发者文档确认。实际做法是把工作项状态变更作为事件源，按上面的映射表生成卡片，推送到负责人或项目群，形成“状态变化—消息生成—触达—点击回到工作项”的闭环。
异常、重复与失败处理预案
对接上线后，失败和重复几乎必然出现，提前约定处置方式比事后排查更省时间。预案要覆盖异常分类、重试规则、去重键、落库位置和告警响应。
接口调用失败按原因分类处理。网络超时通常可重试；凭据失效需要先刷新凭证再重试，连续失败则告警；频率限制要按接口返回的限流信息退避等待，不能立即重放；参数错误属于设计问题，重试无效，应记录原始请求并转人工排查。分类清楚后，重试策略才有针对性。
重试次数和间隔要书面约定，例如最多重试三次、间隔按指数退避，超过上限进入失败队列。去重键建议由业务对象 ID、事件类型和时间戳组合构成，同一事件在重试时复用同一去重键，接收端据此判断是否已处理，避免同一状态变更推送多条。
| 异常类型 | 判定方式 | 处置动作 | 责任人 |
|---|---|---|---|
| 网络超时 | 请求无响应或超时返回 | 按退避策略重试，超上限入失败队列 | 集成负责人 |
| 凭据失效 | 返回鉴权失败错误码 | 刷新凭证后重试，连续失败触发告警 | 凭据保管人 |
| 频率限制 | 返回限流错误码 | 按返回信息等待后重放，控制并发 | 集成负责人 |
| 参数错误 | 返回参数校验失败 | 记录原始请求，停止重试，转人工修正 | 开发负责人 |
| 重复事件 | 去重键已存在 | 丢弃并记录，不重复推送 | 系统自动处理 |
失败消息要落到可查询的位置，比如失败队列表或日志系统，保留原始请求、返回码和重试次数，便于人工补发。补发流程要写明由谁发起、如何选择目标接收人、补发后如何标记状态。告警接收人和响应时限也要明确，例如连续失败达到阈值时通知集成负责人，工作时间内一小时内响应。
联调与可验证结果
联调的目标是证明连接在正常和异常条件下都按预期工作，验收则要留下可复查的证据。用例设计和证据留存要同步进行，避免只凭“收到消息了”就判定完成。
联调用例至少覆盖四类场景：正常推送，验证字段完整、接收人正确、跳转链接可打开；字段缺失，验证占位规则生效、卡片不错位；凭据失效，验证刷新与告警链路；重复事件，验证去重键生效、不产生重复消息。每类用例记录输入、预期结果和实际结果。
- 消息到达截图：包含接收人、消息内容、时间。
- 接口返回码与请求 ID：用于追溯单次调用。
- 日志记录：包含事件来源、去重键、重试次数。
- 失败队列截图：验证异常消息可查询、可补发。
验收通过标准建议写成可核对的条目：四类用例全部通过、失败消息可在队列中查到并完成一次人工补发、告警在设定时限内送达。任一条不通过，回退到上一稳定配置，保留现场日志后再排查，避免在线上反复试错。
上线后设置观察期，通常一到两周，重点监控消息到达率、失败率、重试次数和去重命中数。观察期内每天核对一次失败队列，确认没有积压；观察期结束后形成一份验收记录，包含用例结果、监控数据和遗留问题，作为后续扩展业务对象范围的基线。
常见问题
企业微信侧只申请自建应用，不配置群机器人，能满足研发平台的通知需求吗？
取决于接收对象。自建应用可以按成员推送，也能读取通讯录拿到 UserID，适合任务指派、缺陷提醒这类需要落到个人的通知；群机器人适合把发布公告、构建结果发到固定群聊。如果首期只做个人通知，自建应用即可覆盖；如果还要同步项目群动态，再补充群机器人。两种形态可以并存，但凭据和可见范围要分别登记，避免混用。
研发平台部署在私有网络，没有公网入口，还能做双向回传吗？
双向回传要求企业微信能访问研发平台登记的回调地址，该地址需要公网可达并使用 HTTPS。私有网络环境下通常需要由运维开通反向代理或网关映射，并在企业微信侧完成地址配置和验签。如果短期无法开通，可以先只做单向推送，把回执类需求放到第二阶段，避免因一个地址卡住整体上线。
接收人对照表里出现同名成员或离职成员，应该怎么处理？
对照表以研发平台账号和企业微信 UserID 作为匹配键，姓名只作展示，不参与匹配。同名成员靠账号区分，不会冲突。离职成员的处理要分两步：企业微信侧停用后，UserID 不再有效，推送会失败并进入失败队列；研发平台侧应在成员状态变更时同步更新对照表，把该账号标记为不可推送，并转由项目负责人接收。建议每月核对一次对照表与通讯录的差异。
消息推送失败后人工补发，怎么避免和自动重试重复发送？
补发前先查失败队列中该条记录的状态，确认自动重试已终止再操作。补发时复用原去重键，接收端据此判断是否已处理；如果原消息实际已送达只是回执丢失，重复键会被丢弃，不会产生第二条消息。补发完成后在记录上标注处理人和时间，便于后续核对。
ONES 对接企业微信时，具体能推送哪些业务对象、支持哪些消息类型？
ONES 资料说明支持一键对接企业微信等第三方应用，并提供 API 接口用于与企业系统集成（F3、F4）。具体可推送的业务对象范围、消息卡片字段和配置入口，资料未展开，实施前应查阅对应版本的开发者文档确认。准备阶段可以先按本文的映射表框架列出需求，再对照文档核对可行性。
