研发数据采集的起点是确定要回答的效能问题和指标口径，再盘点承载这些数据的系统与字段，随后选择采集方式、建立映射与校验规则，最终接入看板。本文按这条主线给出可执行步骤与关键产物，指标定义与接口配置分别归入指标体系、工具链集成专题。
要点总览（TL;DR）
- 研发数据采集从要回答的效能问题出发，先划出必采、可选、暂不采集三类范围，再按研发环节盘点数据源。
- 采集方式按数据变化特征选择：批量周期性数据用接口拉取，状态变更用事件推送，无系统留痕的环节用人工补录并配套复核。
- 指标—字段映射表把指标口径固定到来源字段与计算逻辑，统一状态值与时间字段取用规则，是跨系统对齐的核心产物。
- 数据进入统一存储后先做完整性、及时性、一致性三类校验，缺失保留缺口并标注原因，异常明确责任归属。
- 上线前核对范围清单、盘点表、映射表、校验规则与角色确认是否齐备，看板每个指标都能回溯到来源字段。
先定问题再定数据：采集范围怎么划
采集范围从问题反推，避免先接系统再找用途。做法是列出团队当前最想回答的三到五个效能问题，例如“需求从提出到上线平均要多久”“哪个环节返工最多”“版本发布是否按计划完成”，每个问题对应一到三个指标，再由指标确定需要哪些数据。
把候选数据分成三类，形成采集范围清单：
| 类别 | 判断标准 | 处理方式 |
|---|---|---|
| 必采 | 直接支撑当前要回答的问题，缺少则指标无法计算 | 本期纳入采集，明确来源与责任人 |
| 可选 | 对问题有辅助解释作用，但缺少时主指标仍可成立 | 预留字段，视采集成本决定是否本期接入 |
| 暂不采集 | 当前问题用不到，或口径尚未统一 | 记录在清单中，注明后续触发条件 |
范围清单需要写明每项数据的用途、对应指标和本期是否采集，并由效能负责人确认。完成标志是：每个必采项都能指向一个具体问题，暂不采集项都有明确理由。本文讨论采集与呈现，指标如何分级定义属于指标体系的工作，系统间接口认证与连接配置属于工具链集成的工作，两者不在本文展开。
数据源盘点：研发过程数据分布在哪些系统
按研发环节逐段盘点，比按系统逐个罗列更容易发现缺口。常见分布如下：
| 研发环节 | 常见数据源类型 | 典型数据对象 |
|---|---|---|
| 需求 | 需求管理或项目协作系统 | 需求单、状态变更记录、优先级、关联版本 |
| 代码 | 代码托管平台 | 提交记录、合并请求、评审意见、分支 |
| 构建 | 持续集成系统 | 构建任务、构建结果、耗时、触发人 |
| 测试 | 测试管理或自动化测试平台 | 用例、执行记录、缺陷单、通过率 |
| 发布 | 发布或部署系统 | 发布单、环境、发布时间、回滚记录 |
| 缺陷 | 缺陷跟踪系统 | 缺陷状态、严重程度、发现与关闭时间 |
每个数据源在盘点表中记录四项：系统名称、数据对象、可获取字段、更新频率，另加责任人和访问方式备注。字段一栏写到具体字段名，避免只写“状态”这类笼统描述。更新频率用于后续判断采集节奏能否支撑指标统计周期。
盘点时特别标注只有人工记录、无系统留痕的环节，例如线下评审结论、口头约定的排期调整。这类环节要么在协作系统中补建记录，要么列入人工补录范围，不能默认数据会自动产生。盘点表完成后由各系统管理员核对字段是否真实可获取，避免把“界面上能看到”误当成“可以批量导出”。
采集方式与频率：接口拉取、事件推送与人工补录怎么选
三种方式各有适用条件，选择依据是数据变化特征和指标统计周期，而不是系统新旧。
| 方式 | 适用条件 | 注意事项 |
|---|---|---|
| 接口拉取 | 数据批量存在、按周期同步即可满足统计需要，如每日同步需求与缺陷全量或增量 | 明确拉取时间点、增量识别字段、失败重试规则 |
| 事件推送 | 关注状态变更类数据，如需求状态流转、构建完成、发布上线 | 需要处理事件丢失与重复投递，保留事件时间戳 |
| 人工补录 | 无系统留痕或系统字段缺失的环节 | 配套录入模板、必填项与复核人，补录时间与原发生时间分开记录 |
采集频率与指标统计周期匹配：按周统计的指标，每日同步一次通常足够；需要观察当天流动情况的指标，才考虑事件推送。频率过高会增加维护成本，频率过低会让看板数据滞后于团队实际感受，两者都要在决策表中写明理由。
人工补录要设定边界：只补系统确实没有的记录，补录内容需经团队负责人复核，并在数据中标记来源为人工，便于看板区分。完成标志是形成一张采集方式决策表，逐行写明数据对象、采集方式、频率、负责人和失败处理方式。
字段映射与口径对齐：指标—字段映射表怎么建
同一指标在不同系统里往往有不同叫法，映射表的作用是把指标口径固定到具体字段和计算逻辑上。建议包含以下列：
| 列名 | 填写要点 |
|---|---|
| 指标名 | 与指标体系中的名称一致，不另起别名 |
| 口径定义 | 一句话说明分子分母或统计对象，注明包含与排除范围 |
| 来源系统 | 写明系统名称，多来源时分行列出 |
| 来源字段 | 写到字段级，注明字段类型 |
| 计算逻辑 | 给出可直接实现的公式或过滤条件 |
| 责任人 | 对该字段含义负责的人，通常是系统管理员或数据开发 |
状态值与枚举值需要统一处理。各系统对“已完成”的表述可能是不同状态码，映射表中要列出原值到统一值的对照，未识别的新状态默认归入待确认，不能静默丢弃。时间字段要区分创建、开始、完成三类，明确每个指标取哪一个，例如周期类指标取开始到完成，存量类指标取统计时点的状态。跨系统关联需要统一的需求编号或工作项编号作为连接键，映射表中单独标注。
在协作系统承载需求与缺陷的场景中，工作项的类型、状态和自定义字段本身就是映射的来源。ONES Performance 可同步 Project 中的业务数据，管理者能从统一入口查看多项目、多团队、多流程的效能表现，映射表可以把指标直接对应到工作项字段与状态流转上，减少跨系统拼接。具体可同步的数据对象范围与字段清单，需在实际环境中核对后再写入映射表。
采集校验与异常处理：怎么判断数据可用
数据进入统一存储后，先校验再上看板。校验分三类，每类给出可执行的规则：
| 校验类型 | 检查内容 | 示例规则 |
|---|---|---|
| 完整性 | 必填字段是否为空、记录数是否与来源系统一致 | 当日同步的需求记录数与该系统当日新增数偏差超过阈值即告警 |
| 及时性 | 数据是否在约定时间前到达 | 每日同步任务在设定时间未完成则通知负责人 |
| 一致性 | 同一对象在不同系统中的关键字段是否矛盾 | 需求状态为已上线但发布系统无对应发布记录，标记待核 |
缺失数据的处理方式是保留缺口并标注原因，不用默认值填充后直接计算，否则指标会失真。重复数据按业务主键去重，保留最新更新时间的一条，去重规则写入校验清单。异常上报要指定责任归属：采集任务失败由数据开发处理，字段含义争议由系统管理员确认，业务状态与实际不符由团队负责人核实。每条异常记录处理状态和关闭时间，形成可追溯的处置记录。
ONES Performance 具备数据同步与统一展示能力，可将多来源数据汇总后用于报表；校验规则仍需要在采集链路上单独定义，工具承担同步与呈现，口径与规则由团队确认。
角色分工与交付物：谁负责哪一段
采集链路涉及四类角色，职责按环节划分，交接物明确到文档或表格。
| 角色 | 主要职责 | 交付物 |
|---|---|---|
| 效能负责人 | 确定要回答的问题、确认指标口径与采集范围 | 采集范围清单、指标口径确认记录 |
| 系统管理员 | 提供各系统字段清单、确认状态值含义、核对数据真实性 | 数据源盘点表、状态值对照表 |
| 数据开发 | 实现采集任务、建立映射与校验、处理异常 | 指标—字段映射表、校验规则清单、异常处置记录 |
| 团队负责人 | 复核人工补录内容、确认业务状态与实际一致 | 补录复核记录、异常核实结论 |
评审节点设在两处：范围清单与数据源盘点完成后评审一次，确认采什么、从哪采；映射表与校验规则完成后评审一次，确认口径与规则可执行。两次评审的输出都需签字或留痕确认，作为后续变更的基线。
示例：一条需求交付数据的采集链路
以“需求从创建到上线”为例，演示从数据源到看板的完整链路。
第一步，确定指标为需求交付周期，口径定义为需求创建时间到首次上线时间的自然日天数，排除已取消需求。第二步，盘点数据源：需求创建与状态变更来自项目协作系统，上线记录来自发布系统，两者以需求编号关联。第三步，选择采集方式：需求数据每日接口拉取增量，状态变更通过事件推送补充，发布记录每日拉取。第四步，填写映射表：指标名“需求交付周期”，来源系统为协作系统与发布系统，来源字段为创建时间与上线时间，计算逻辑为上线时间减创建时间，责任人为数据开发。第五步，设定校验规则：创建时间为空的需求进入待补录队列；上线时间早于创建时间的记录标记异常并通知团队负责人；同一需求存在多条上线记录时取最早一条。第六步，数据进入统一存储后接入看板，看板上的每个数值都能回溯到上述字段。
这个例子中，人工补录只用于创建时间缺失的历史需求，补录后标记来源，看板可按来源筛选对比。整个链路的关键产物就是范围清单、盘点表、映射表、校验规则四份文件。
完成检查：采集上线前的核对项
上线前逐项核对，全部通过再开放看板：
- 采集范围清单已确认，每个必采项对应具体问题，暂不采集项有理由。
- 数据源盘点表覆盖全部必采环节，字段写到字段级，人工留痕环节已标注。
- 采集方式决策表写明每个数据对象的采集方式、频率、负责人和失败处理。
- 指标—字段映射表完整，状态值对照与时间字段取用规则已确认。
- 校验规则清单覆盖完整性、及时性、一致性三类，异常责任归属明确。
- 四类角色均已确认各自交付物，两次评审记录留痕。
- 看板上每个指标都能回溯到来源系统与来源字段，抽查若干条记录与源系统一致。
核对中发现缺口，回到对应环节补齐，不带着未确认的口径上线。上线后保留一份变更记录，字段或口径调整时同步更新映射表与校验规则，保证看板长期可用。
常见问题
团队规模较小、系统不多，是否也需要建完整的映射表和校验规则？
需要保留映射表与校验规则，但可以按规模裁剪。系统少、数据来源单一时，映射表可以只覆盖当前看板用到的指标，校验规则先做完整性与及时性两类，一致性校验在出现跨系统关联需求后再补。判断标准是看板上的数值能否解释来源：只要有人问“这个数怎么算出来的”能当场回答，映射表就起到了作用。规模扩大或新增数据源时，再按同一结构扩展，避免重新设计。
历史数据缺失严重，采集上线时要不要先补齐再开放看板？
不必等历史数据补齐再上线。更稳妥的做法是先保证新产生数据的采集链路稳定，历史缺口在映射表或校验清单中登记范围与原因，看板上对涉及历史区间的指标标注数据起始时间。人工补录只用于确有业务记录可查的部分，补录后标记来源为人工，便于与系统采集数据区分。若历史缺口影响趋势判断，可先缩短看板展示的时间窗口，等新数据积累到足够周期再扩展。
同一指标在多个系统都有记录，以哪个系统为准？
以业务发生环节最接近的系统为准，并在映射表中写明主来源与辅助来源。例如需求状态以项目协作系统为准，上线时间以发布系统为准，两者通过统一的需求编号关联。出现矛盾时按校验规则标记待核，由团队负责人确认业务实际状态，确认结果回写到映射表的口径说明中。主来源一经确定，不因某次数据好看而临时切换，否则指标会失去可比性。
采集频率提高后维护成本上升，怎么判断是否值得？
用指标统计周期和团队使用场景来判断。按周或按月统计的指标，每日同步一次通常已经够用；只有需要观察当天流动情况、支持每日站会或实时预警的场景，才值得引入事件推送。提高频率前先确认下游是否真的会用到更细的时间粒度，以及失败重试、事件去重等配套处理是否到位。频率调整后观察一段时间的异常率和维护投入，再决定保留还是回退。
采集链路上线后，字段或口径发生变化怎么处理？
把映射表与校验规则当作需要版本管理的文档。字段调整、状态值新增或口径修订时，先更新映射表并记录变更时间与原因，再同步调整采集任务和校验规则，最后通知看板使用方。未识别的新状态默认归入待确认，不静默丢弃或直接计入某一类。保留变更记录的价值在于，指标出现波动时能区分是业务变化还是口径调整造成的。
