制品元数据记录要回答四个问题：这个制品是什么、从哪里来、是否完整可信、交付给谁并保留多久。围绕这四项用途，至少保留身份标识、来源追溯、完整性与质量、流转与保留四类信息。字段取舍以“能定位、能追溯、能校验、能交接”为标准，先建立最小必填集，再按交付对象和合规要求扩展，避免字段堆砌或关键信息缺失。
要点总览（TL;DR）
- 制品元数据记录按四类信息组织：身份标识、来源追溯、完整性与质量、流转与保留，每类承担定位、追溯、校验、交接中的一项用途。
- 最小必填集按四项用途各取至少一个字段判定，先保证记录基本可用，再按交付对象和合规要求扩展签名、扫描结论、发布批次等字段。
- 来源与校验值字段应在构建阶段由流水线自动写入，测试结论、交付对象、保留期限等人工确认字段在发布与交付前校验节点设置必填。
- 字段命名与取值格式需统一约定并版本化维护，新增字段经评审后纳入规范，历史记录按生效批次处理。
- 交付前按完整性、格式一致性、来源可追溯、校验匹配、交接信息明确、归档状态六项逐项核对，必填缺失或校验值不一致应阻断交付。
一份制品元数据记录应包含哪些字段
制品元数据记录的价值在于让一个已构建的交付物在离开构建环境后仍可被识别、追溯和验证。字段按四类组织，每类承担一项明确用途。下表给出可直接采用的字段清单，必填性按一般交付场景标注，团队可结合自身交付要求调整。
| 分类 | 字段名 | 必填性 | 用途 |
|---|---|---|---|
| 身份标识 | 制品名称 | 必填 | 识别制品在业务中的名称，与需求或模块对应 |
| 版本号 | 必填 | 区分同一制品的不同发布版本，支持比对与回退 | |
| 唯一标识（ID） | 必填 | 在系统内唯一确定一条制品记录，避免同名版本混淆 | |
| 制品类型 | 必填 | 说明是安装包、镜像、库文件、配置文件还是文档包，决定后续校验与部署方式 | |
| 来源追溯 | 源码仓库地址 | 必填 | 定位代码来源仓库 |
| 提交号（Commit） | 必填 | 精确到构建所用的代码版本 | |
| 构建任务 | 必填 | 记录产生该制品的流水线或构建任务 | |
| 构建号 | 必填 | 区分同一任务下的多次构建 | |
| 构建时间 | 必填 | 确定制品产生时点，便于与变更记录对齐 | |
| 触发人 | 必填 | 明确谁发起或批准了这次构建 | |
| 完整性与质量 | 校验值（哈希） | 必填 | 验证制品在存储和传输中未被篡改或损坏 |
| 签名信息 | 按需 | 对外交付或高安全要求场景下证明制品来源可信 | |
| 扫描结论 | 按需 | 记录依赖漏洞、许可证或安全扫描结果 | |
| 测试结论 | 必填 | 说明该版本通过了哪些测试，作为放行依据 | |
| 流转与保留 | 存储位置 | 必填 | 指明制品在仓库或制品库中的实际路径 |
| 发布批次 | 按需 | 将多个制品归入同一次发布，支持整体回溯 | |
| 交付对象 | 必填 | 记录交付给哪个客户、环境或下游团队 | |
| 保留期限 | 必填 | 明确制品及记录需保存多久，支撑审计与问题复现 | |
| 责任人 | 必填 | 指定对该制品记录负责维护和答疑的人员 |
必填与按需的划分依据是交付场景。内部联调环境使用的临时构建，可以只保留身份标识和来源追溯字段；对外交付、客户验收或受监管的发布，则需要补齐签名、扫描结论和发布批次。字段清单本身不是目的，关键是每个字段都能在后续某个动作中被用到。
如何确定最小必填字段集与扩展规则
最小必填集按四项用途各取至少一个字段来判定：能定位，至少要有制品名称、版本号和唯一标识；能追溯，至少要有源码仓库、提交号和构建号；能校验，至少要有校验值和测试结论；能交接，至少要有存储位置、交付对象、保留期限和责任人。满足这四项，记录就具备了基本可用性。
扩展字段由交付对象和合规要求决定。面向外部客户的交付，通常需要补充签名信息和扫描结论；涉及多制品协同发布的场景，需要增加发布批次；受行业监管的项目，可能需要按审计要求延长保留期限或增加审批记录。扩展时应逐条说明字段的用途和填写责任，避免出现无人维护的字段。
字段命名与取值格式需要统一约定，否则跨批次数据无法比对。常见约定包括：版本号采用固定分段规则，校验值注明算法类型，时间统一使用同一时区和格式，人员标识使用工号或账号而非姓名简称。这些约定应写入团队规范，并在构建脚本或记录模板中固化。
新增字段应经过评审，确认其用途、填写时机和责任角色后再纳入规范，并对规范做版本化维护。规范版本变化时，需说明历史记录是否需要补填、新字段从哪个批次开始生效。这样既能控制字段膨胀，也能保证新旧记录在同一套口径下可读。
记录生成与维护的操作步骤
元数据记录应尽量在流程中自动产生，人工只补充无法自动获取的部分。按构建、发布、交付前校验、归档四个阶段推进，每个阶段都有明确的输入、动作、输出和完成标志。
| 阶段 | 输入 | 动作 | 输出 | 完成标志 |
|---|---|---|---|---|
| 构建阶段 | 代码提交、构建任务配置 | 由构建流水线自动写入制品名称、版本号、唯一标识、制品类型、源码仓库、提交号、构建任务、构建号、构建时间、触发人和校验值 | 带有来源与完整性字段的初始记录 | 构建成功且校验值已生成，记录中来源字段无空缺 |
| 发布阶段 | 初始记录、测试报告、发布计划 | 补充测试结论、扫描结论、签名信息、发布批次和存储位置 | 可供交付评审的完整记录 | 质量结论字段已由对应角色确认 |
| 交付前校验 | 完整记录、交付清单 | 核对必填字段是否齐全、格式是否一致、校验值与实际制品是否匹配、交付对象是否填写 | 校验通过的交付记录 | 检查清单全部通过，异常项已处理 |
| 归档与保留 | 已交付记录 | 按保留期限归档，冻结关键字段，保留期内如需更正以追加说明方式处理 | 可检索的历史记录 | 记录状态标记为已归档，责任人和保留期限可查 |
构建阶段是自动采集的重点。把来源字段和校验值的写入放进流水线，可以减少人工填写遗漏，也让每条记录天然带有可追溯的构建链路。发布阶段补充的字段多依赖人工判断，例如测试结论需要测试角色确认，交付对象需要交付负责人填写，这些字段应在流程节点上设置必填校验。
归档后的记录应保持稳定。保留期内发现字段错误时，采用追加更正说明的方式处理，保留原始值，避免历史记录被静默改写。保留期限到期前，由责任人确认是否可以清理，涉及审计或客户约定的记录按约定延长。
在记录生成与归档环节，团队可以用 ONES 承载制品相关的工作项与文档状态。ONES 当前方案覆盖需求、基线、版本、变更、测试与发布，并把测试用例、缺陷、版本和发布过程关联到需求链路中，便于在出现问题时定位影响范围。制品记录可以作为交付物模板的一部分沉淀为可复用资产，具体字段的承载方式需结合团队实际配置确认。
角色分工与各环节交付物
字段由谁填写、何时确认，直接决定记录能否在需要时被信任。下表按角色列出主要责任字段和对应交付物，团队可据此分配权限与流程节点。
| 角色 | 负责字段 | 填写时点 | 交付物 |
|---|---|---|---|
| 构建与发布执行人 | 身份标识类字段、来源追溯类字段、校验值、存储位置 | 构建完成时自动或手动写入，发布时补充存储位置 | 初始元数据记录、构建日志 |
| 质量与测试角色 | 测试结论、扫描结论 | 测试与扫描完成后 | 测试报告、扫描报告及结论确认 |
| 交付负责人 | 交付对象、发布批次、保留期限、责任人 | 交付评审前 | 交付清单、保留策略说明 |
| 记录审核人 | 字段完整性与一致性复核、异常处理结论 | 交付前校验与归档时 | 校验记录、异常处理说明 |
审核责任需要独立于填写责任。构建执行人对自己产生的来源字段负责，审核人则从交付视角检查字段是否齐全、结论是否有依据。发现字段缺失或结论与报告不一致时，应退回对应角色补充，而不是由审核人代填。异常处理结论也应写入记录，便于后续复盘。
示例：一个发布包的元数据记录
以下为演示情景，制品名称、版本号、提交号等均为示意数据，不代表真实项目。
| 分类 | 字段 | 示例值 |
|---|---|---|
| 身份标识 | 制品名称 | 订单服务安装包 |
| 身份标识 | 版本号 | 2.4.0 |
| 身份标识 | 唯一标识 | artifact-20240612-0047 |
| 身份标识 | 制品类型 | 安装包 |
| 来源追溯 | 源码仓库 | order-service 主仓库 |
| 来源追溯 | 提交号 | a1b2c3d |
| 来源追溯 | 构建任务 / 构建号 | order-service-release / #218 |
| 来源追溯 | 构建时间 / 触发人 | 2024-06-12 14:30 / 张工 |
| 完整性与质量 | 校验值 | SHA-256 摘要值（示例略） |
| 完整性与质量 | 测试结论 | 回归测试通过，遗留缺陷 0 个阻断级 |
| 完整性与质量 | 扫描结论 | 依赖扫描无高危漏洞 |
| 流转与保留 | 存储位置 | 制品库 release/order-service/2.4.0 |
| 流转与保留 | 发布批次 | 2024-06 客户A交付批次 |
| 流转与保留 | 交付对象 | 客户A 生产环境 |
| 流转与保留 | 保留期限 / 责任人 | 24 个月 / 李工 |
这条记录体现的追溯链路是：从交付对象客户A生产环境出发，经发布批次找到该安装包，再通过提交号 a1b2c3d 和构建号 #218 回到具体代码版本与构建过程，最后用校验值确认交付的制品与构建产物一致。任何一环缺失，追溯都会中断。
完成检查：元数据记录是否可用
交付前按以下清单逐项核对，全部通过方可视为记录可用。
- 字段完整性：必填字段无空缺，按需字段在适用场景下已填写。
- 格式一致性：版本号、时间、校验值算法、人员标识符合团队约定，跨记录可比对。
- 来源可追溯：源码仓库、提交号、构建任务与构建号能对应到实际构建，构建时间与触发人可查。
- 完整性可校验：校验值与实际制品匹配，测试结论和扫描结论有对应报告支撑。
- 交接信息明确：存储位置可访问，交付对象、保留期限和责任人已填写且经确认。
- 归档状态：记录已标记归档，关键字段处于冻结状态，更正以追加说明方式留存。
出现以下情况应阻断交付并返工：必填字段缺失且无法补充；校验值与实际制品不一致；测试结论缺少报告依据；交付对象或保留期限未确认。返工后需重新执行校验，并在记录中保留异常处理说明，确保问题可回溯。
常见问题
内部联调用的临时构建，也需要保留完整的元数据记录吗？
可以按场景裁剪。内部联调环境的临时构建，通常保留身份标识和来源追溯字段即可满足定位与追溯需求，完整性与质量类字段中的签名、扫描结论可以不填。裁剪的前提是明确该制品不对外交付、不进入客户环境；一旦同一制品被选为对外发布的基础，应在发布前补齐校验值、测试结论、交付对象和保留期限等字段，并重新执行交付前校验。
构建流水线自动采集字段后，人工还需要补充哪些内容？
自动采集适合来源追溯类字段和校验值，例如源码仓库、提交号、构建任务、构建号、构建时间、触发人。人工补充集中在需要判断的结论类字段：测试结论需要测试角色依据报告确认，扫描结论需要安全或质量角色确认，交付对象、发布批次、保留期限和责任人需要交付负责人填写。建议在发布和交付前校验节点把这些字段设为必填，避免记录在归档时才发现空缺。
保留期内发现元数据记录填错了，应该直接修改还是另作处理？
已归档的记录建议保持原始值，采用追加更正说明的方式处理，写明错误字段、正确取值、更正原因和更正人。直接改写会让历史记录失去可信度，也无法解释此前基于错误字段做出的判断。若错误涉及校验值或交付对象这类关键字段，应同时评估已交付制品是否需要重新校验或通知接收方，并把处理结论一并写入记录。
多个制品在同一次发布中交付，元数据记录如何组织？
为每个制品保留独立记录，再用发布批次字段把它们归入同一次发布。这样既能按单个制品追溯来源与校验值，也能按批次整体回溯本次交付包含哪些制品、交付给谁。批次层面的信息如交付对象、保留期限可以在批次记录中统一维护，制品记录引用批次标识，减少重复填写。批次内任一制品发生变更时，应更新批次记录并说明变更范围。
用 ONES 承载制品元数据记录时，需要提前确认什么？
ONES 方案覆盖需求、基线、版本、变更、测试与发布，并把测试用例、缺陷、版本和发布过程关联到需求链路中，可作为制品记录关联交付链路的承载环境（F1、F3）。实施前建议确认三点：制品元数据字段以何种对象或模板承载、校验值与扫描结论等字段如何录入、保留期限与归档冻结如何管理。这些细节需结合团队实际配置确认，字段清单本身仍以本文的四类用途为准。
