研发平台对接钉钉前，需要把四类信息准备齐：钉钉侧的应用身份与权限、研发平台侧的接入参数与消息出口、双方对齐的人员与消息字段口径，以及测试上线所需的负责人和回滚安排。这份清单面向研发平台管理员、钉钉企业管理员、集成开发负责人和测试负责人，在立项准备、联调前、上线前三个节点逐项核对。范围限定在企业应用连接，身份目录认证与团队日常沟通规范另作处理。ONES 的开放接口与钉钉对接能力可用于承载接入任务、字段确认和上线评审的管理动作，具体配置以实际环境和官方文档为准。
要点总览（TL;DR）
- 钉钉侧先拿到企业内部应用的AppKey、AppSecret、AgentId，并把消息发送、通讯录读取等实际需要的权限点开通到位，同时登记出口IP白名单与回调域名。
- 研发平台侧要确定回调接收服务的部署位置与网络可达性、需要推送的事件范围、账号匹配键（手机号、工号或邮箱）及匹配失败的处理规则。
- 联调前把人员与部门标识、消息卡片字段、跳转与免登逻辑、重复消息与失败重试口径逐项对齐，并用测试企业和测试群走完整路径。
- 每项检查写成可观察的通过标准并留存证据，登记负责人与复检日期；权限未开通、回调不可达、账号映射未验证、密钥保管不合规属于阻断项。
- 上线条件为阻断项全部清零且关键消息链路测试通过，同时确认回滚触发条件、执行人和上线后的观察期与异常上报路径。
谁在什么时点用这份清单
这份清单解决的是“谁在什么时候检查什么”的问题。对接工作跨两个系统、多个角色，如果只在联调当天才把各方拉到一起，常见结果是权限没批完、回调地址没登记、账号匹配键没定，联调被迫中断。把角色和时点先固定下来，后续每一项才有明确的归属。
| 角色 | 立项准备 | 联调前 | 上线前 |
|---|---|---|---|
| 研发平台管理员 | 确认对接范围与消息推送场景，指定集成开发负责人 | 确认回调服务已部署、密钥保管方式已确定 | 确认阻断项清零，签署上线判定 |
| 钉钉企业管理员 | 确认可创建企业内部应用，明确权限审批流程 | 确认权限点已开通、可见范围已配置 | 确认应用已发布到目标范围 |
| 集成开发负责人 | 梳理接口清单与字段映射草案 | 完成回调连通性验证与账号映射验证 | 提供联调日志与测试用例结果 |
| 测试负责人 | 准备测试企业与测试群 | 执行关键消息链路测试 | 出具测试通过结论与遗留问题清单 |
范围边界需要提前说清：本文覆盖的是研发平台作为企业应用接入钉钉、向钉钉推送消息与卡片、从钉钉侧获取必要身份标识的连接工作。钉钉与企业身份目录的认证对接、单点登录配置、团队日常沟通与信息同步规范，属于另外的工作项，不并入本清单，否则检查项会失焦，责任人也难以界定。
准备阶段：钉钉侧应用与权限信息
钉钉侧的准备核心是拿到一组可用的应用身份，并把调用所需权限逐项开通到位。这一阶段没完成，研发平台侧的任何开发都无法进入真实联调。以下检查表按顺序推进，前一项未通过不建议进入下一项。
| 检查项 | 通过标准 | 证据 | 负责人 |
|---|---|---|---|
| 创建企业内部应用 | 应用已创建，应用类型为企业内部应用，名称与用途可识别 | 应用详情页截图 | 钉钉企业管理员 |
| 获取 AppKey、AppSecret、AgentId | 三项凭据已取得并存入约定的密钥管理位置，未出现在代码仓库或聊天记录中 | 密钥登记记录（不含明文） | 集成开发负责人 |
| 接口权限点开通 | 消息发送、通讯录读取等实际需要的权限点状态为已开通，审批已结束 | 权限审批记录或权限列表截图 | 钉钉企业管理员 |
| 服务器出口 IP 白名单 | 研发平台消息发送服务的出口 IP 已登记，测试调用不再被拒绝 | 白名单配置截图与一次成功调用记录 | 集成开发负责人 |
| 回调域名与可信域名登记 | 接收钉钉回调的域名已按要求登记，域名与实际服务一致 | 域名配置截图 | 集成开发负责人 |
| 应用可见范围 | 可见范围覆盖试点部门，非试点人员不可见 | 可见范围配置截图 | 钉钉企业管理员 |
权限点要按实际调用清单逐项核对，不要按“可能用到”批量申请。申请范围过宽会拉长审批时间，也会让后续安全评审难以解释。AppSecret 属于敏感凭据，取得后应立即进入密钥管理流程，并明确轮换责任人；如果企业有凭据轮换周期，需要在立项时就确认轮换时研发平台侧如何同步更新。
准备阶段：研发平台侧接入信息
研发平台侧要确定的是“消息从哪里发出、发到哪里、以什么身份对应到人”。这三件事决定联调能否一次跑通。建议在开发前形成一份接入参数表，由集成开发负责人维护，研发平台管理员确认。
| 检查项 | 通过标准 | 证据 | 负责人 |
|---|---|---|---|
| 回调接收服务部署 | 服务已部署在约定环境，具备公网可达地址，健康检查接口返回正常 | 部署记录与健康检查结果 | 集成开发负责人 |
| 网络可达性 | 研发平台到钉钉接口、钉钉回调到研发平台两个方向均连通 | 连通性测试记录 | 集成开发负责人 |
| 消息推送范围 | 明确列出需要推送的事件类型，例如工作项状态变更、审批结果、到期提醒，并标注优先级 | 推送场景清单 | 研发平台管理员 |
| 账号映射规则 | 匹配键已选定（手机号、工号或邮箱），冲突处理规则已写明 | 映射规则说明与样例数据比对结果 | 集成开发负责人 |
| 密钥存储与轮换 | 存储位置、访问权限、轮换周期与责任人已登记 | 密钥管理登记表 | 研发平台管理员 |
账号映射是最容易在联调阶段返工的一项。选择匹配键时，要看企业目录中哪一字段唯一且稳定：手机号变更频率低但存在一人多号的情况，工号稳定但外部协作人员可能没有，邮箱在跨组织协作中更通用。无论选哪个，都要写明匹配失败时的处理方式，例如进入待人工确认队列，而不是静默丢弃。推送范围也要克制，先覆盖关键事件，避免上线初期消息量过大导致用户屏蔽应用。
在任务管理层面，可以把上述检查项作为工作项录入 ONES，按准备、联调、上线三个阶段设置状态，把权限审批记录、配置截图和联调日志作为附件挂在对应工作项下。ONES 提供开放接口用于与企业系统集成，也支持对接钉钉，接入过程中的任务分派、字段确认和上线评审可以在同一处留痕，便于上线前集中核对。
联调阶段：字段与消息口径核对
联调阶段的目标是把双方对“同一条消息”的理解对齐。很多对接问题并非接口不通，而是字段含义不一致：研发平台认为的负责人是工号，钉钉侧需要的是用户标识；消息卡片上的跳转链接在测试环境可打开，在生产环境因域名未登记而失效。以下核对表按字段、消息、异常三类组织。
| 核对项 | 通过标准 | 证据 | 负责人 |
|---|---|---|---|
| 人员标识对应 | 抽样人员在两边的标识可一一对应，匹配成功率符合约定 | 抽样比对表 | 集成开发负责人 |
| 部门与群组标识 | 部门层级与群组标识的对应关系已确认，变更时同步方式已约定 | 映射关系表 | 集成开发负责人 |
| 消息卡片字段 | 标题、正文、状态、时间等字段在钉钉端显示完整，无截断或乱码 | 卡片截图 | 测试负责人 |
| 跳转链接 | 从钉钉卡片跳转研发平台目标页面成功，登录态处理符合预期 | 跳转测试记录 | 测试负责人 |
| 重复消息处理 | 同一事件重复触发时，接收端按约定去重，用户不收到重复提醒 | 重复触发测试结果 | 集成开发负责人 |
| 失败重试与限流 | 发送失败按约定重试，触发限流时有退避策略，失败消息可追溯 | 异常场景测试日志 | 集成开发负责人 |
| 测试环境准备 | 测试企业与测试群已建立，测试人员已加入，与生产环境隔离 | 测试环境清单 | 测试负责人 |
免登与跳转逻辑需要在联调阶段就确定：用户从钉钉消息点进研发平台时，是携带身份标识直接进入，还是先经过一次登录。两种方式对研发平台侧的改造量不同，也影响后续的安全评审。建议在测试企业中用真实账号走一遍完整路径，把结果记录为测试用例，而不是只在开发机上验证接口返回。
每项检查的通过标准与证据
检查清单失效的常见原因是把建议写成了勾选项。“权限已申请”“回调已配置”这类描述无法判断是否真的完成。可用的通过标准应当是一个可观察的结果：一次成功的调用、一条在钉钉端正常显示的卡片、一份审批结束的记录。写法上可以遵循三个要点：结果可观察、范围可界定、失败可复现。
| 检查项 | 通过标准 | 证据 | 负责人 |
|---|---|---|---|
| 接口权限开通 | 使用正式凭据调用目标接口返回成功，而非仅显示“审批中” | 调用返回记录与权限列表截图 | 钉钉企业管理员 |
| 回调可达 | 钉钉侧触发一次测试事件，研发平台接收服务日志中出现对应记录 | 接收日志片段 | 集成开发负责人 |
| 账号映射 | 抽样不少于约定数量的人员全部匹配成功，失败样本有处理记录 | 比对结果表 | 集成开发负责人 |
| 消息链路 | 从研发平台触发到钉钉端收到卡片，端到端时延在约定范围内 | 测试用例执行结果 | 测试负责人 |
每项检查都要登记负责人和检查时点，建议在检查表中增加“检查日期”和“复检日期”两列。未通过项不要直接删除或改成“后续处理”，应保留在原表中，记录未通过原因、整改责任人和复检安排。复检通过后再更新状态，这样上线评审时能看清每一项的完整过程，而不是只看最终结论。
阻断项与上线完成条件
并非所有检查项都同等重要。有些项未完成只影响体验，有些项未完成则会导致上线后消息发不出、人员对不上、故障无法回退。后者应列为阻断项，在上线评审中逐项确认清零。
| 阻断项 | 判定标准 | 未清零的后果 |
|---|---|---|
| 权限未开通 | 实际调用所需权限点均为已开通状态 | 消息发送与通讯录读取直接失败 |
| 回调不可达 | 钉钉触发事件后研发平台侧有接收记录 | 事件无法回传，状态不同步 |
| 账号映射未验证 | 抽样人员匹配成功且有失败处理规则 | 消息推送给错误人员或无人接收 |
| 密钥未按规范保管 | 凭据不在代码与聊天记录中，轮换责任人已确定 | 凭据泄露风险，轮换时可能中断服务 |
上线完成条件建议写成两条：全部阻断项清零并有证据留存；关键消息链路测试通过，覆盖发送、接收、跳转和异常重试。两条同时满足才进入上线操作。上线前还需确认回滚方案与责任人：回滚触发条件是什么，例如消息发送失败率超过约定阈值或账号匹配异常比例升高；回滚时是关闭推送开关、回退应用配置，还是暂停回调接收；由谁在什么时限内决定并执行。这些内容写进上线判定表，比口头约定更可靠。
上线后设置观察期，建议覆盖一个完整的工作周期，重点观察消息送达情况、用户反馈和异常日志。异常上报路径要提前告知试点用户：遇到收不到消息、点开链接异常等情况，向谁反馈、以什么形式反馈、多久响应。观察期结束且无阻断级问题，再将应用可见范围扩大到全量人员。
常见问题
钉钉应用权限还在审批中，可以先开始研发平台侧的开发吗？
可以先做不依赖真实调用的准备工作，例如梳理推送场景清单、确定账号匹配键、搭建回调接收服务并完成本地自测。但真实联调必须等权限点状态变为已开通，否则接口调用会直接失败，联调日志也无法作为上线证据。建议把权限审批作为联调启动的前置条件，在检查表中记录审批发起日期和预计完成时间，审批未结束时安排字段映射草案评审等不阻塞的工作。
账号匹配键选手机号、工号还是邮箱，怎么定？
判断依据是企业在钉钉通讯录和研发平台中哪一字段唯一且稳定。手机号变更频率低，但存在一人多号或换号的情况；工号稳定，但外部协作人员可能没有；邮箱在跨组织协作中更通用。选定后要写明匹配失败的处理方式，例如进入待人工确认队列并通知对接负责人，避免消息静默丢弃。建议在联调前用抽样数据做一次比对，确认匹配成功率符合约定后再进入消息链路测试。
测试环境验证通过，上线后仍可能出现哪些问题？
常见问题集中在环境差异上：生产域名未登记导致卡片跳转失效，生产出口IP未加入白名单导致发送被拒，生产人员范围比测试企业大导致部分账号匹配失败。上线前应把测试环境用到的域名、IP、可见范围在生产环境逐项复核，并在观察期内重点查看发送失败日志和用户反馈。观察期建议覆盖一个完整工作周期，确认无阻断级问题后再扩大应用可见范围。
上线后发现消息推送异常，回滚应该怎么执行？
回滚方案要提前写清三件事：触发条件，例如发送失败率超过约定阈值或账号匹配异常比例明显升高；回滚动作，例如关闭推送开关、回退应用配置或暂停回调接收；决策与执行责任人及时限。上线判定表中记录这些内容，出现异常时按预定路径执行，避免临时讨论延误。回滚后保留异常日志，用于定位原因并安排复检。
接入过程中的检查项和证据放在哪里管理比较合适？
可以把检查项作为工作项录入 ONES，按准备、联调、上线三个阶段设置状态，将权限审批记录、配置截图和联调日志作为附件挂在对应工作项下。ONES 提供开放接口用于与企业系统集成，也支持对接钉钉，接入任务的分派、字段确认和上线评审可以在同一处留痕，上线前集中核对时不必在多个工具之间来回查找。
