研发平台对接钉钉的验收，需要把“能连上”拆成可逐项判断的检查表。这份清单按联调前准备、消息推送与工作项卡片、待办与审批回传、权限与安全、阻断项判定五个阶段组织，每项写明通过标准、证据和负责人，适用于上线评审和观察期复核。文中以研发平台与钉钉的集成为对象，目录认证与单点登录配置不在本文展开；ONES 可作为承载检查项、证据附件与遗留问题跟踪的工具，具体对接能力以实际配置和产品文档为准。
要点总览（TL;DR）
- 验收按联调前准备、消息与卡片、待办与审批回传、权限与安全、阻断项判定五个阶段推进，每项写明通过标准、证据和负责人。
- 通过标准要写成可观察的结果，例如抽查10条消息四项字段一致、无权限账号三处均被拦截，截图与日志按检查项编号归档。
- 消息大面积丢失、越权可见、回传导致状态错乱、凭证泄露风险四类问题默认列为阻断项，关闭后才能给出验收结论。
- 验收在联调前、上线前、上线后观察期三个时点分别签字，前置条件未满足时不进入联调。
- 检查项、证据附件与遗留问题需要统一承载位置，ONES 可对接钉钉并承载验收工作项与整改跟踪，具体范围以实际配置为准。
谁在什么时点使用这份验收清单
这份清单由四类角色共同使用：研发平台管理员负责集成配置与功能验证，钉钉管理员负责应用创建、权限申请与组织可见范围，业务负责人确认消息内容与流程是否符合实际工作习惯，安全或 IT 负责人确认凭证、数据可见范围与审计记录。四类角色在三个时点分别签字，避免把准备事项和验收事项混在一起。
| 时点 | 主要动作 | 签字确认人 | 输出物 |
|---|---|---|---|
| 联调前准备核对 | 确认对接范围、应用与权限、测试账号与测试群、人员映射口径 | 研发平台管理员、钉钉管理员 | 准备阶段检查表（全部项通过） |
| 上线前验收 | 逐项执行消息、卡片、待办、审批回传与权限用例 | 研发平台管理员、业务负责人、安全或 IT 负责人 | 验收记录、证据清单、阻断项关闭记录 |
| 上线后观察期复核 | 核对真实流量下的推送成功率、回传一致性与告警记录 | 研发平台管理员、业务负责人 | 观察期复核记录、遗留问题清单 |
进入联调前，需要满足三个前置条件：本期对接范围已经书面确认，测试企业或测试组织已经开通并可操作，双方管理员都能登录各自后台完成配置。前置条件未满足时，联调阶段的问题往往难以区分是配置缺失还是功能缺陷，返工成本会明显上升。
联调前准备检查项
准备阶段的目标是把账号、组织、权限和配置一次对齐，让后续联调只验证功能本身。以下检查项全部通过后再约定联调时间。
| 检查项 | 通过标准 | 证据 | 负责人 |
|---|---|---|---|
| 对接范围清单 | 消息通知、工作项卡片、待办、审批回传逐项标注“本期纳入”或“后续版本”，并由业务负责人确认 | 范围确认邮件或评审记录 | 业务负责人 |
| 钉钉侧应用创建 | 应用已创建，所需权限已申请并通过，回调地址与可信域名配置完成且与研发平台配置一致 | 应用配置截图、权限审批记录 | 钉钉管理员 |
| 研发平台侧集成配置 | 集成入口所需参数填写完整，保存后无报错，连接测试返回成功 | 配置页截图、连接测试结果 | 研发平台管理员 |
| 测试账号与测试群 | 至少准备一个管理员账号、两个普通成员账号和一个测试群，成员覆盖不同项目角色 | 账号清单、群成员截图 | 双方管理员 |
| 组织与人员映射口径 | 明确以工号、手机号还是外部 ID 对齐，并抽样核对 5 名以上人员映射结果一致 | 映射对照表、抽样核对记录 | 研发平台管理员 |
人员映射口径需要在准备阶段定下来。映射字段选错，后续消息接收人、待办归属和审批回传都会出现错位，而且这类问题在联调中表现为“偶发收不到”，排查耗时较长。抽样核对时建议覆盖离职重入、手机号变更、一人多项目等边界人员。
消息推送与工作项卡片检查项
这一阶段验证研发平台的事件能按预期推送到钉钉，并在钉钉内正确呈现、正确跳转。检查以单向推送为主，回传闭环放到下一阶段。
| 检查项 | 通过标准 | 证据 | 负责人 |
|---|---|---|---|
| 触发事件覆盖 | 工作项创建、状态变更、指派、评论、到期提醒逐项触发一次，钉钉侧均收到对应消息 | 事件触发记录与钉钉消息截图对照 | 研发平台管理员 |
| 消息内容正确性 | 标题、状态、负责人、链接与研发平台实际数据一致，抽查 10 条无错位 | 逐条对照截图 | 业务负责人 |
| 卡片跳转 | 点击卡片能打开对应工作项详情；无权限用户点击后出现明确提示，不暴露详情内容 | 有权限与无权限两种账号的跳转截图 | 研发平台管理员 |
| 接收范围 | 按项目、角色或群配置的接收人与预期名单一致，非相关人员不收到消息 | 接收人名单与实收记录 | 业务负责人 |
| 消息频率 | 批量操作场景下消息合并或限流符合约定，不出现同一工作项短时间重复刷屏 | 批量操作前后的消息记录 | 研发平台管理员 |
通过标准要写成可观察的结果。例如“消息内容正确”应落到“抽查 10 条，标题、状态、负责人、链接四项全部一致”，而不是“基本正常”。截图和日志按检查项编号归档，上线评审时直接调取。
待办、审批与状态回传检查项
回传闭环是验收中最容易出现状态错乱的环节。检查需要同时覆盖正向用例和异常用例，正向用例证明流程能走通，异常用例证明重复、乱序和失败不会污染研发平台数据。
| 检查项 | 通过标准 | 证据 | 负责人 |
|---|---|---|---|
| 待办生成 | 研发平台产生的待办在钉钉待办中可见，标题、截止时间与来源工作项一致 | 两侧待办截图对照 | 研发平台管理员 |
| 待办完成回传 | 在钉钉完成待办后，研发平台对应待办状态同步为完成，延迟在约定范围内 | 操作时间与状态变更日志 | 研发平台管理员 |
| 审批结果回传 | 同意、拒绝、撤回三种结果分别在研发平台落到正确状态，工作项流转符合流程定义 | 三种用例的操作记录与状态截图 | 业务负责人 |
| 重复与乱序回调 | 同一事件重复回调或乱序到达时，研发平台结果幂等，不产生重复记录或状态回退 | 模拟重复回调的测试记录 | 研发平台管理员 |
| 失败重试与告警 | 回传失败时系统有重试或告警，人工可按记录补处理，补处理后数据一致 | 失败注入记录、告警截图、补处理记录 | 研发平台管理员 |
异常用例建议在测试环境主动构造：断开回调地址模拟失败、重复发送同一回调模拟幂等、调换回调顺序模拟乱序。每类用例记录预期结果与实际结果，实际结果与预期不符时直接进入阻断项评估。
权限、安全与可见范围检查项
对接不应扩大数据可见范围。这一阶段的检查由安全或 IT 负责人主导确认，功能正确但权限越界的系统不能上线。
| 检查项 | 通过标准 | 证据 | 负责人 |
|---|---|---|---|
| 人员可见范围 | 钉钉侧接收人只能看到其有权限的工作项，用无权限账号验证消息、卡片、跳转三处均被拦截 | 无权限账号的验证截图 | 安全或 IT 负责人 |
| 敏感字段 | 消息与卡片中不包含不应外发的字段，字段清单经业务与安全双方确认 | 字段清单、消息样例 | 安全或 IT 负责人 |
| 凭证管理 | 应用密钥、回调校验方式明确保管人，轮换流程与周期已书面约定 | 凭证管理约定文档 | 双方管理员 |
| 日志与审计 | 推送与回传记录可查询，保留期限明确，能按工作项或人员检索 | 日志查询截图、保留期限说明 | 研发平台管理员 |
凭证轮换需要提前约定操作窗口。轮换期间旧凭证失效，若没有同步更新研发平台配置，消息推送和回传会同时中断，因此轮换步骤应写入运维手册并安排一次演练。
阻断项与完成条件
阻断项指不能带病上线的问题，需要在验收结论中单独列出并跟踪到关闭。以下四类问题默认列为阻断项：消息大面积丢失或长时间延迟；无权限人员可见工作项内容；回传导致研发平台状态错乱或产生重复记录；凭证存在泄露风险或保管责任不清。
文案措辞、卡片样式、消息排版等不影响数据正确性和权限边界的问题，列为非阻断项，可放入观察期整改，但需要指定整改责任人和完成时间。阻断项与非阻断项的划分由验收评审会确认，避免执行过程中随意降级。
验收完成条件包括三条：全部阻断项关闭并有关闭证据；关键用例（消息触发、卡片跳转、待办完成回传、审批三种结果回传、无权限拦截）全部通过；观察期内无重复故障。满足条件后，验收记录、证据清单和遗留问题清单归档到双方可访问的位置，由四类角色分别签字确认。
在验收流程中，检查项、证据附件和遗留问题需要有统一的承载位置。ONES 提供 API 接口用于与企业系统集成，并支持对接钉钉等第三方应用，团队可以把验收检查项建成工作项、将截图与日志作为附件留存、把遗留问题转为待办跟踪到关闭，使验收记录与后续整改在同一处可查。具体对接范围与配置方式以实际产品文档和账号配置为准。
常见问题
对接范围只做消息推送、暂不做审批回传，验收清单要怎么裁剪？
按 S2 的对接范围清单逐项标注，把审批回传相关检查项标为“后续版本”，本期验收只保留已纳入的用例。裁剪后仍要保留三类检查：消息触发与内容正确性、卡片跳转与无权限提示、接收范围是否符合预期。S5 的权限与安全项不随范围裁剪，只要消息会发到钉钉，可见范围和敏感字段就必须验证。S6 的阻断项判定同样保留，范围缩小只是减少用例数量，不降低上线门槛。
联调阶段消息偶发收不到，验收时应该怎么定位和记录？
先回到 S2 的人员映射口径核对，偶发收不到多数与映射字段、接收人配置或群成员变动有关。定位时按“事件触发记录—研发平台推送日志—钉钉侧接收记录”三段对照，确认消息在哪一段中断。记录时写明触发时间、工作项编号、预期接收人和实际接收情况，作为证据附在对应检查项下。若同类现象在多个事件上重复出现，按 S6 的“消息大面积丢失”进入阻断项评估，不带着问题进入观察期。
上线后观察期一般看多久，出现什么问题需要回退？
观察期长度由验收评审会结合业务节奏确定，清单不预设固定天数。观察期重点核对三项：真实流量下的推送成功率、待办与审批回传的状态一致性、告警记录是否有人处理。出现回传导致研发平台状态错乱、无权限人员可见工作项内容、凭证失效导致推送与回传同时中断这三类情况时，应暂停对接并回退到上一稳定配置，修复后重新执行相关用例，而不是在观察期内边用边改。
凭证轮换期间如何避免消息推送和回传同时中断？
轮换前把步骤写入运维手册，明确新旧凭证的生效与失效时间点、研发平台配置的更新人和更新时间。操作时先在研发平台侧更新凭证并完成一次连接测试，确认推送与回传均正常后再停用旧凭证；若两侧配置无法同时更新，安排在低峰时段并提前通知业务方。轮换完成后保留一次演练记录，作为 S5 凭证管理检查项的证据。轮换责任人和周期在验收阶段就应书面约定，避免上线后无人负责。
用 ONES 承载验收检查项和遗留问题，需要提前准备什么？
ONES 提供 API 接口用于与企业系统集成，并支持对接钉钉等第三方应用，可把验收检查项建成工作项、将截图与日志作为附件留存、把遗留问题转为待办跟踪到关闭。准备阶段需要确认承载验收记录的项目空间、检查项字段（通过标准、证据、负责人、阻断标记）以及遗留问题的流转状态，并明确谁有权限查看和更新。具体对接范围、接口权限与配置方式以实际产品文档和账号配置为准。
