研发平台对接飞书的验收，要回答的是“这套连接能不能放心上线”。验收范围覆盖研发平台与飞书之间的应用连接、消息与事件通道，按连接可用、消息与事件送达、字段映射正确、权限与安全合规、异常可恢复、运行可观测六类检查项逐项判定。每项检查都要写明通过标准、证据和负责人；连接不通、消息丢失、越权可见、无回退手段、关键字段映射错误属于阻断项，未关闭不通过验收。这份清单供上线前联调完成、试运行结束、正式切换前三个时点使用，验收记录与阻断项闭环可以放在 ONES 的工作项和文档中跟踪。
要点总览（TL;DR）
- 验收范围限定在研发平台与飞书之间的应用连接、消息与事件通道，按准备、联调、放行三个时点分段判定。
- 六类检查项为连接可用、消息与事件送达、字段映射正确、权限与安全合规、异常可恢复、运行可观测，每项须写明通过标准、证据和负责人。
- 连接不通、消息丢失、越权可见、无回退手段、关键字段映射错误属于阻断项，未关闭不通过验收。
- 通过标准采用可观察结果加判定条件的写法，证据以配置截图、调用日志、消息记录和测试用例执行结果为主，统一归档可追溯。
- 验收完成需同时满足阻断项全部关闭、证据齐全、四类角色签字确认三个条件。
谁在什么时点使用这份验收清单
这份清单的验收对象是研发平台与飞书之间的应用连接、消息与事件通道，包括研发平台向飞书推送消息、飞书侧操作回传研发平台这两条链路。它用于上线前的集中判定，日常运维监控、告警处置另有运行手册，两者不混用。飞书目录认证、企业身份账号统一登录属于另一个集成项目，团队日常沟通规范也不在本清单范围内，验收启动时应在范围说明中写明排除项，避免验收会上反复拉扯边界。
参与验收的角色分四类。研发平台管理员负责集成配置、回调地址、字段映射和日志取证；飞书应用管理员负责应用创建、权限范围、可用范围与消息通道配置；安全或合规审核人负责权限边界、敏感内容可见性和数据流向的确认；业务验收人从使用侧确认消息是否送到正确的人、工作项状态是否真实更新。角色可以兼任，但签字责任要分开落到人。
| 阶段 | 时点标志 | 主要参与角色 | 签字确认内容 |
|---|---|---|---|
| 准备阶段 | 联调开始前 | 研发平台管理员、飞书应用管理员 | 前置条件齐备，可以进入联调 |
| 联调与功能验收 | 联调完成、试运行结束 | 研发平台管理员、飞书应用管理员、安全或合规审核人 | 功能检查项通过，证据已归档 |
| 放行判定 | 正式切换前 | 四类角色共同签字 | 阻断项全部关闭，同意上线 |
三个时点的签字含义不同：准备阶段签的是“可以开始联调”，功能验收签的是“检查项已验证”，放行签的是“同意正式切换”。把三者合并成一次签字，容易让未验证的项目混进上线范围。
上线前准备阶段检查项
准备阶段的目标是在联调开始前把前置条件确认清楚，减少联调中途返工。这一阶段的检查项不涉及功能效果，只判断条件是否具备。下表可直接作为准备阶段检查表使用，“阻断”列标注该项未完成时是否阻止进入联调。
| 检查项 | 通过标准 | 证据 | 负责人 | 阻断 |
|---|---|---|---|---|
| 飞书侧应用已创建 | 应用存在且状态可用，应用名称、负责人登记在案 | 应用管理页截图 | 飞书应用管理员 | 是 |
| 权限范围已确认 | 申请的消息发送、事件订阅等权限与对接方案逐条对应，无多余授权 | 权限配置截图与方案对照表 | 飞书应用管理员、安全审核人 | 是 |
| 可用范围已确认 | 应用可见范围与试点部门、试点群组一致，未全租户放开 | 可用范围配置截图 | 飞书应用管理员 | 是 |
| 研发平台集成配置就绪 | 应用凭证、回调地址、消息模板等配置项填写完整，测试环境与生产环境分开 | 配置页面截图 | 研发平台管理员 | 是 |
| 网络连通性 | 研发平台到飞书开放接口、飞书回调到研发平台的网络路径均可达，防火墙策略已放行 | 连通性测试记录 | 研发平台管理员 | 是 |
| 测试资源就绪 | 测试账号、测试群组、测试项目空间已建立，成员覆盖授权与非授权两类 | 资源清单 | 研发平台管理员 | 是 |
| 消息模板与字段映射草案 | 草案覆盖标题、状态、负责人、链接等关键字段，每条映射有责任人 | 映射草案文档 | 研发平台管理员 | 否 |
| 变更窗口与回退方案 | 切换时间窗已登记，回退触发条件、回退操作步骤和决策人已明确 | 变更单与回退方案 | 研发平台管理员 | 是 |
准备阶段最常见的返工点是权限范围一次申请过多、可用范围直接放开到全租户。前者让安全审核无法通过，后者让试点阶段的消息打扰到无关人员。两项都应在进入联调前收紧到试点范围，后续按需扩围。
联调与功能验收阶段检查项
联调阶段验证的是实际效果：消息能不能送到、事件能不能回传、字段对不对、权限守不守得住。每项检查都要留下可复核的证据，不能只凭口头确认。下表按检查项、通过标准、证据和阻断标记组织。
| 检查项 | 通过标准 | 证据 | 阻断 |
|---|---|---|---|
| 研发平台事件触发飞书消息 | 在工作项创建、状态变更、指派等约定事件发生时，消息在约定时限内送达指定会话或群组，内容与模板一致 | 消息记录截图、调用日志 | 是 |
| 飞书侧操作回传研发平台 | 在飞书中执行约定的操作后，研发平台对应工作项状态、负责人等字段在约定时限内更新 | 操作前后工作项截图、回调日志 | 是 |
| 关键字段映射 | 标题、状态、负责人、链接四类字段逐条比对一致，状态值映射表无遗漏项 | 字段映射对照表、抽样比对记录 | 是 |
| 重复推送处理 | 同一事件重复触发时，接收侧按约定去重或幂等处理，不产生重复消息或重复状态变更 | 重复触发测试记录 | 否 |
| 乱序与延迟处理 | 人为制造延迟或乱序后，最终状态与源系统一致，不出现状态回退或覆盖错误 | 测试用例执行结果 | 否 |
| 权限范围验证 | 非授权账号在飞书中看不到敏感消息内容，也无法通过链接进入受限工作项 | 非授权账号视角截图 | 是 |
| 消息内容合规 | 消息中不包含超出约定范围的敏感字段，链接可正常打开且跳转目标正确 | 消息样例、跳转记录 | 否 |
| 异常场景 | 飞书接口超时或返回错误时，研发平台记录失败并按约定重试，重试结果可查 | 错误注入测试记录、重试日志 | 否 |
重复推送、乱序与延迟这三项容易被跳过，因为正常联调时很少自然出现。建议在测试环境主动构造：同一事件连续触发两次、人为延迟一条消息、调换两条消息的到达顺序，观察最终状态是否与源系统一致。这类测试记录本身就是验收证据。
权限验证要用非授权账号实际登录飞书查看，不能只看配置页面。配置正确但消息内容里带了敏感字段、或者链接跳转绕过了权限校验，都属于越权可见，按阻断项处理。
每项检查的通过标准与证据要求
验收结论要经得起复核，关键在于通过标准写得可观察、证据留得可追溯。通过标准统一采用“可观察结果＋判定条件”的写法：先写看到什么，再写满足什么条件算通过。例如“消息送达指定群组”是观察对象，“在约定时限内、内容与模板一致、群组成员正确”是判定条件。避免写“消息推送正常”“权限配置合理”这类无法判定的表述。
证据类型按检查项性质选择，常用四类：配置截图用于证明权限、可用范围、回调地址等静态配置；调用日志用于证明消息发送、回调接收的实际发生；消息记录用于证明送达内容和接收对象；测试用例执行结果用于证明重复、乱序、异常等场景的处理。截图要包含配置页面标识和时间，日志要能定位到具体事件，测试记录要写明执行人、执行时间和结果。
| 证据类型 | 适用检查项 | 留存要求 |
|---|---|---|
| 配置截图 | 应用创建、权限范围、可用范围、集成配置 | 含页面标识与截取时间，按“阶段-检查项-日期”命名 |
| 调用日志 | 消息发送、事件回调、重试 | 保留原始日志片段，标注事件标识便于检索 |
| 消息记录 | 消息送达、内容合规、权限可见性 | 保留接收端截图，注明接收账号与群组 |
| 测试用例执行结果 | 重复推送、乱序延迟、异常场景 | 写明执行人、时间、步骤与结果 |
证据统一存放在验收记录所在的项目空间或文档中，按阶段建目录，文件名包含检查项编号。未通过项要记录现象、影响范围、责任人和复测时点，复测通过后补录新证据，原记录保留不删除，形成完整的整改轨迹。验收任务、证据附件和阻断项状态可以在 ONES 的工作项与文档中统一管理，评审时按检查项逐条核对，避免证据散落在聊天记录里。
阻断项与验收完成条件
阻断项是决定放行与否的硬条件，出现即暂停验收，关闭后才能重新判定。本清单的阻断项包括五类：连接不通，即研发平台与飞书之间的消息或回调链路无法建立；消息丢失，即约定事件触发后消息未送达且无失败记录；越权可见，即非授权人员能看到敏感内容或进入受限工作项；无回退手段，即切换后出现问题无法按预定步骤回退；关键字段映射错误，即标题、状态、负责人、链接中出现错位或缺失。
| 阻断项 | 判定依据 | 关闭条件 | 复验方式 |
|---|---|---|---|
| 连接不通 | 连通性测试或联调中链路建立失败 | 链路恢复并有成功调用记录 | 重新执行连通性与消息往返测试 |
| 消息丢失 | 事件已触发但接收侧无记录，发送侧也无失败日志 | 定位原因并修复，补充失败记录与重试机制 | 重复触发同一事件验证送达 |
| 越权可见 | 非授权账号看到敏感内容或进入受限工作项 | 权限配置或内容裁剪完成 | 用非授权账号重新验证 |
| 无回退手段 | 回退方案缺失或回退步骤无法执行 | 回退方案登记并演练通过 | 按方案执行一次回退演练 |
| 关键字段映射错误 | 标题、状态、负责人、链接出现错位、缺失或状态值不对应 | 映射修正并全量比对通过 | 抽样比对并核对状态映射表 |
非阻断项按限期整改处理：记录问题现象、影响范围、责任人和整改期限，在验收记录中标注“带条件通过”，并在约定时点复验。非阻断项不阻止上线，但要在试运行期内关闭，逾期未关闭的升级为阻断项重新判定。
验收完成需同时满足三个条件：阻断项全部关闭并有复验记录；各检查项证据齐全、命名规范、可追溯；四类角色在验收记录上签字确认。遗留问题单独建跟踪清单，明确责任人和复验时点，由研发平台管理员在切换后按周复核，直到全部关闭。签字前建议做一次证据抽查，随机抽取若干检查项核对证据与结论是否一致，抽查发现证据缺失的，该项退回重验。
常见问题
验收时发现消息偶尔延迟送达，但最终都到了，算阻断项吗？
按本清单的判定口径，消息丢失指事件已触发但接收侧无记录、发送侧也无失败日志，属于阻断项。偶发延迟但最终送达、且有日志可查的情况，归入乱序与延迟检查项，按非阻断项记录并限期整改。需要关注的是延迟是否超出约定时限、是否导致状态回退或覆盖错误；如果延迟引发了最终状态与源系统不一致，就应按阻断项处理。
试点阶段只开放给一个部门，验收时要不要按全租户范围重新验证权限？
验收按实际开放范围判定。试点阶段可用范围限定在试点部门时，权限验证用该范围内的授权账号和非授权账号对比即可。全租户放开属于范围变更，应在扩围前单独做一次权限复验，重点确认新增范围内非授权人员看不到敏感内容、链接跳转不绕过权限校验。把扩围复验纳入变更流程，比在首次验收时按全租户模拟更贴近实际上线节奏。
回退方案演练需要做到什么程度才算通过？
回退方案通过的标准是：触发条件、操作步骤和决策人已书面登记，并且在测试环境按方案完整执行过一次回退，回退后研发平台与飞书两侧的状态与切换前一致。演练记录要写明执行人、执行时间、每一步的实际结果和耗时。只写了方案未演练，按“无回退手段”阻断项处理；演练中发现步骤缺失或执行失败的，修正后重新演练并补录记录。
非阻断项在试运行期内没关闭，还能正式切换吗？
非阻断项不阻止上线，但要在验收记录中标注“带条件通过”，写明问题现象、影响范围、责任人和整改期限。逾期未关闭的，升级为阻断项重新判定，此时不再放行。建议在切换前对非阻断项做一次盘点，把影响面大、修复周期长的项提前评估是否应转为阻断项，避免切换后被动回退。
验收证据存放在聊天记录或邮件里可以吗？
不建议。证据要可追溯、可复核，统一存放在验收记录所在的项目空间或文档中，按阶段建目录，文件名包含检查项编号。配置截图要含页面标识和截取时间，日志要能定位到具体事件，测试记录要写明执行人、时间和结果。散落在聊天记录里的截图难以检索，评审时无法逐条核对，容易导致检查项退回重验。验收任务、证据附件和阻断项状态可以在 ONES 的工作项与文档中统一管理。
