构建结果报告围绕一次构建的可判定结论组织：先写清构建标识与触发来源，再给出通过或失败结论和关键证据，最后写失败原因定位、责任人与后续动作。编写时按“结论先行—证据支撑—动作闭环”的顺序落笔，字段固定、口径统一，由流水线自动采集客观数据，构建负责人补充判断与处置。评审时以他人能否据此复现同一次构建、能否据此做出放行或修复决策，作为报告写完的标准。
要点总览（TL;DR）
- 构建结果报告按“结论先行—证据支撑—动作闭环”组织：开头写构建状态、构建编号与触发来源，中段列提交、制品、测试与检查结果，结尾写失败阶段、原因初判、责任人与后续动作。
- 字段分必填与按需两类：构建状态、编号、提交、分支、触发来源、时间与耗时、测试与检查结果为必填；制品标识、失败阶段、原因初判、责任人、后续动作在成功或失败时按需填写。
- 编写分五步：确定模板与状态枚举、流水线自动采集客观数据、定位失败阶段与首个错误、给出处置结论与期限、归档并通知相关角色；人工只补充判断类内容。
- 角色分工按数据产出、结论判断、原因确认、验证确认、放行判断划分，构建负责人判断“发生了什么”，开发提交人确认“为什么发生、怎么修”。
- 完成检查以结论与证据一致、可复现、可决策、字段完整、分发到位五项为标准，前四项为阻断项，分发不到位可限时补做。
构建结果报告先写什么：核心结构与最小字段集
报告的第一屏应当让读者在十秒内知道三件事：这次构建是谁触发的、对应哪份代码、结果是什么。把构建状态、构建标识和触发来源放在开头，再往下展开证据与处置，读者不必翻到日志末尾才能判断这次构建能不能用。
字段设计上区分必填与按需两类。必填字段保证任何一次构建都能被唯一识别和追溯；按需字段随构建结果变化，例如成功构建通常不需要失败原因，失败构建则必须填写失败阶段与首个错误。这样处理可以避免模板为了覆盖所有情况而膨胀成日志堆砌。
| 字段 | 填写内容 | 必填/按需 | 承担的判断 |
|---|---|---|---|
| 构建状态 | 成功、失败、中止、不稳定（模板内固定枚举） | 必填 | 结论 |
| 构建编号 | 流水线生成的唯一标识 | 必填 | 可追溯 |
| 代码版本/提交 | 提交哈希，必要时附提交说明 | 必填 | 可复现 |
| 分支 | 构建所在分支或标签 | 必填 | 可复现 |
| 触发来源 | 触发人、触发方式（手动、提交触发、定时） | 必填 | 责任起点 |
| 开始与结束时间、耗时 | 时间戳与总时长 | 必填 | 异常识别 |
| 制品或包标识 | 制品名称与版本号，成功构建必填 | 按需 | 可交付 |
| 单元测试与静态检查结果 | 通过数、失败数、覆盖率或检查告警数 | 必填 | 质量证据 |
| 失败阶段与日志位置 | 失败发生在哪个阶段、日志或报告链接 | 失败时必填 | 定位依据 |
| 失败原因初判 | 已确认或待确认的原因描述 | 失败时必填 | 处置起点 |
| 责任人 | 跟进修复的具体人员 | 失败时必填 | 动作归属 |
| 后续动作与期限 | 修复、回滚、重跑等动作及完成时间 | 失败时必填 | 闭环 |
状态取值需要在模板中固定下来。同一类结果在不同人笔下写成“失败”“不通过”“报错”，统计时就会失真；把枚举写进模板，填写人只能从中选择，报告之间才具备可比性。
编写步骤：从流水线数据到一份可判定报告
编写动作可以拆成五步，每一步都有明确输入、动作、输出和完成标志。核心原则是：客观数据由流水线产出，人工只补充判断类内容，减少凭印象填写。
| 步骤 | 输入 | 动作 | 输出 | 完成标志 |
|---|---|---|---|---|
| 1. 确定模板与口径 | 团队约定的字段清单、状态枚举 | 固化模板，明确必填项与状态取值 | 可复用的报告模板 | 模板中每个字段都有填写说明和取值约束 |
| 2. 采集客观数据 | 流水线执行记录 | 由流水线自动写入构建编号、提交、分支、时间、耗时、测试与检查结果 | 报告的数据部分 | 必填客观字段无空缺，数值与流水线记录一致 |
| 3. 定位失败 | 构建日志、测试报告 | 确定失败阶段与首个错误，附日志或报告链接 | 失败定位段落 | 读者能按链接直接看到出错位置 |
| 4. 给出处置结论 | 失败定位、提交人与模块归属 | 写原因初判、责任人、后续动作与期限 | 处置段落 | 责任人和动作明确到人、到时间 |
| 5. 归档与分发 | 完成的报告 | 存入约定位置，通知相关角色 | 可检索的归档记录 | 相关角色已收到通知，报告可按构建编号检索 |
第二步与第三步之间有一个容易忽略的细节：失败阶段要写到具体环节，例如“单元测试阶段第 3 个用例失败”，而不是笼统写“测试失败”。首个错误指日志中第一条导致中断的错误，后续错误往往是它的连锁反应，抓住首个错误能显著缩短排查时间。
第四步的原因初判要区分“已确认”和“待确认”。已确认表示有人复现或从日志直接读出原因；待确认表示有怀疑方向但尚未验证。两种写法混用会让后续跟进者误判进度，因此在模板中为原因加一个确认状态字段是值得的。
第五步的归档位置和通知对象应在模板中预先写明。报告散落在聊天记录里，等于没有归档；按构建编号可检索，才能支撑后续的追溯和复盘。
角色与交付物：谁采集、谁判断、谁确认
报告由多方共同完成，各角色只对自己能判断的部分负责。把分工写进模板，可以避免报告变成构建负责人一人的主观描述。
| 角色 | 职责 | 交付物 | 交接时点 |
|---|---|---|---|
| 流水线/构建脚本 | 自动产出客观数据与日志 | 构建编号、提交、分支、耗时、测试与检查结果、日志链接 | 构建结束时自动写入 |
| 构建负责人 | 给出结论、失败初判与处置建议 | 状态确认、失败阶段、原因初判、后续动作建议 | 构建结束后第一时间 |
| 开发提交人 | 确认失败原因并执行修复 | 原因确认结论、修复提交、重跑结果 | 收到通知后按期限反馈 |
| 测试或质量角色 | 在需要时确认验证结果 | 验证结论、遗留问题说明 | 修复完成待验证时 |
| 评审或发布确认角色 | 依据报告做放行判断 | 放行或阻断结论 | 发布前评审时 |
构建负责人与开发提交人的边界值得单独说明：构建负责人判断“这次构建发生了什么”，开发提交人确认“为什么发生、怎么修”。前者依据日志和流水线数据即可完成，后者需要代码层面的判断。把两者混在一起，容易出现报告写了原因却无人验证的情况。
当团队使用 ONES 承载研发过程时，流水线数据可以自动同步执行状态和日志，构建记录与需求、任务等工作项建立关联，报告中的提交、构建与发布过程能在项目、迭代和需求视图中查看。这样归档与分发不必依赖人工转贴，评审角色也能在同一处看到构建结论与对应工作项，再做出放行判断。具体同步字段与视图形式以实际集成配置为准。
示例：一次失败构建的报告怎么写
以下为演示场景，不对应真实项目数据。某分支一次构建在单元测试阶段失败，按最小字段集填写如下。
| 字段 | 填写示例 |
|---|---|
| 构建状态 | 失败 |
| 构建编号 | build-2041 |
| 代码版本/提交 | a1b2c3d（提交说明：调整订单校验逻辑） |
| 分支 | feature/order-validate |
| 触发来源 | 提交触发，提交人：开发甲 |
| 开始与结束时间、耗时 | 10:02 开始，10:11 结束，耗时 9 分钟 |
| 单元测试与静态检查结果 | 单元测试 312 个用例，失败 1 个；静态检查无新增告警 |
| 失败阶段与日志位置 | 单元测试阶段，用例 OrderValidatorTest.shouldRejectEmptyAmount 失败；日志见流水线构建详情页 |
| 失败原因初判 | 待确认：空金额校验分支的断言与实际返回值不一致，疑似本次提交修改了校验顺序 |
| 责任人 | 开发甲 |
| 后续动作与期限 | 当日 18:00 前确认原因并提交修复，修复后重跑构建并回填结果 |
这份示例体现了几条填写规律。状态与失败阶段相互对应，读者从“失败”进入“单元测试阶段”不会产生歧义；失败定位写到具体用例名，配合日志链接，他人可以独立复现；原因初判标注“待确认”，与责任人的修复动作形成前后衔接；后续动作带明确期限，报告因此具备可跟进性。
常见误写是只写“构建失败，请相关同学看一下”。这类写法缺少构建编号、失败阶段和责任人，读者既无法定位同一次构建，也无法判断该由谁处理。另一种误写是把日志整段粘贴进报告，证据看似充分，关键的首个错误反而被淹没。正确做法是引用日志位置，正文只写失败阶段与首个错误。
完成检查：报告可用的判断标准
报告是否写完，由评审者按下列清单逐项核对。任一项不通过即视为未完成，需要返工后再进入放行或复盘环节。
| 检查项 | 通过标准 | 不通过时的处理 |
|---|---|---|
| 结论与证据一致 | 状态、失败阶段、日志内容三者可相互对应 | 阻断，补齐证据后重新提交 |
| 可复现 | 他人依据构建编号与提交能定位到同一次构建 | 阻断，补全构建标识与提交信息 |
| 可决策 | 失败时有明确责任人与后续动作及期限 | 阻断，补写处置段落 |
| 字段完整 | 必填项无空缺，状态取值符合模板约定 | 阻断，按模板补齐 |
| 分发到位 | 报告已归档到约定位置并通知相关角色 | 不阻断评审，但需在当日补做归档与通知 |
前四项属于阻断项，因为它们直接决定报告能否支撑放行判断和问题追溯；分发不到位影响的是协作效率，可以在评审通过后限时补做。把阻断项与非阻断项分开，评审时就不必在格式细节上反复拉扯，注意力可以集中在结论与证据是否成立。
这套检查标准也可以反过来用于模板设计：如果某个字段从未在任何检查项中被用到，就应考虑它是否值得保留。字段越少而每项都有判断用途，报告被认真填写的概率越高。
常见问题
构建结果报告和流水线日志有什么区别，能不能直接用日志代替报告？
两者承担的判断不同。流水线日志是原始执行记录，用于定位具体错误；构建结果报告是在日志之上形成的可判定结论，回答这次构建能不能用、谁跟进、下一步做什么。直接用日志代替报告，读者需要自行从大量输出中找首个错误和失败阶段，放行判断和追溯都会变慢。报告应引用日志位置，正文只写失败阶段与首个错误，把日志作为证据链接而非正文主体。
构建状态写成“失败”“不通过”“报错”有区别吗，为什么要在模板里固定枚举？
同一类结果在不同人笔下用不同词，统计时会被拆成多个口径，报告之间失去可比性。建议在模板中固定状态枚举，例如成功、失败、中止、不稳定，填写人只能从中选择。这样构建成功率、失败分布等汇总才有统一基础，评审者也能快速识别状态含义。枚举一旦确定，后续新增状态应走模板变更，避免个人临时造词。
失败原因初判写“待确认”会不会显得报告没写完，应该等到查清再写吗？
不必等到查清。失败报告的价值之一是让跟进者知道当前进展和怀疑方向，原因初判标注“待确认”并写明怀疑依据，比空着或强行写一个未验证的结论更有用。关键是把确认状态显式写出来，让读者区分“已确认”和“待确认”，避免把怀疑当成定论。后续由开发提交人确认原因并回填修复结果，报告随之更新。
团队刚起步，字段能不能先少填几项，等流程稳定再补全？
可以按最小字段集起步，但建议先保证构建状态、构建编号、代码提交、分支、触发来源、时间与耗时、测试与检查结果这几项必填，它们决定报告能否被唯一识别和追溯。失败阶段、原因初判、责任人、后续动作在失败时必填，成功构建可按需填写。字段越少而每项都有判断用途，报告被认真填写的概率越高；后续根据评审中实际用到的字段逐步补充，比一开始堆满字段更可持续。
构建结果报告归档在哪里比较合适，通知哪些人？
归档位置应满足按构建编号可检索这一条件，避免散落在聊天记录里。通知对象至少包括开发提交人、构建负责人和需要依据报告做放行判断的评审角色；测试或质量角色在修复待验证时加入。归档与通知对象建议在模板中预先写明，评审时把分发到位作为检查项，但不作为阻断项，可在评审通过后限时补做。
