制品元数据记录要围绕“可识别、可追溯、可复现、可审计”四类用途保留信息，核心字段包括制品标识、来源与构建信息、内容完整性、依赖与环境、质量与放行状态、流转与存放六类。字段按用途分层设置，必填项保证追溯闭环，选填项按安装包、镜像、文档、配置包等交付物类型补充。下面给出可直接套用的字段清单、落地五步、角色分工、填写示例与完成检查。
要点总览（TL;DR）
- 制品元数据记录围绕识别、追溯、复现、审计四类用途保留六类信息：标识、来源与构建、内容完整性、依赖与环境、质量与放行状态、流转与存放。
- 必填字段以能否形成追溯闭环为判断标准，选填字段按安装包、镜像、文档、配置包等交付物类型补充，避免堆砌无关信息。
- 落地分五步：梳理交付物类型与追溯场景、定义字段口径与命名规范、确定必填规则与校验方式、在构建或发布环节嵌入记录动作、抽样核对与修订。
- 构建或发布执行人负责来源与完整性字段，开发负责人确认依赖与版本口径，测试角色填写测试结论，放行审批人填写放行状态，配置或发布管理角色维护字段规范并抽查记录完整性。
- 缺失来源信息或校验值的记录不能用于交付审计，需补齐后重新核对；字段规范应有版本号，字段调整时同步更新并通知相关角色。
先定用途：元数据记录要回答哪几个问题
字段设计从用途出发，比从“别人记了什么”出发更可靠。一条制品元数据记录通常要回答四类问题：这是什么制品、它从哪里来、能否按记录重新构建、谁批准了它进入交付。四类用途对应不同的最小信息需求，字段清单由此推导，避免堆砌无关字段。
| 用途 | 要回答的问题 | 最小信息需求 |
|---|---|---|
| 识别制品 | 这是什么、哪个版本、属于哪类交付物 | 制品名称、版本号、制品类型、唯一标识 |
| 追溯来源 | 由哪份代码、哪次构建产生 | 代码仓库与提交版本、构建任务编号、构建时间、构建执行人 |
| 复现构建 | 换一台机器能否构建出同样内容 | 依赖清单、构建环境与工具链版本、校验值 |
| 支撑审计与放行 | 谁测过、谁批准、当前是否可交付 | 测试结论、评审记录、放行状态、责任人、变更记录 |
字段范围随交付物类型调整。安装包需要重点记录依赖与运行环境；容器镜像需要记录基础镜像与镜像摘要；文档类交付物侧重版本、评审与放行记录；配置包则需要记录适用的环境范围与配置项清单。团队可以先按主要交付物类型各列一份字段草案，再合并成统一规范。
本文聚焦可交付资产本体的元数据，组织配置基线的建立与维护、制品仓库底层存储与开发实现不在讨论范围内，相关主题可另行查阅研发配置与基线管理资料。
核心答案：制品元数据字段清单与必填规则
下表给出六类字段的完整清单。必填与选填的划分原则是：缺少该字段会导致追溯链断裂或无法验证制品完整性的，设为必填；仅用于补充说明、按交付物类型差异较大的，设为选填。取值来源优先选择系统自动采集，人工补录集中在判断类信息上。
| 类别 | 字段名 | 说明 | 取值来源 | 必填/选填 | 填写时点 |
|---|---|---|---|---|---|
| 标识 | 制品名称 | 与交付物清单一致的正式名称 | 构建配置或人工录入 | 必填 | 构建产出时 |
| 标识 | 版本号 | 遵循团队版本命名规范 | 构建任务自动生成 | 必填 | 构建产出时 |
| 标识 | 制品类型 | 安装包、镜像、文档、配置包等 | 构建配置 | 必填 | 构建产出时 |
| 标识 | 唯一标识 | 全局不重复的编号，用于跨系统引用 | 系统生成 | 必填 | 入库时 |
| 来源 | 代码仓库与提交版本 | 仓库地址与提交哈希 | 构建系统自动采集 | 必填 | 构建触发时 |
| 来源 | 构建任务编号 | 可回查的构建记录编号 | 构建系统自动采集 | 必填 | 构建触发时 |
| 来源 | 构建时间 | 构建开始与完成时间 | 构建系统自动采集 | 必填 | 构建完成时 |
| 来源 | 构建执行人 | 触发构建的人员或服务账号 | 构建系统自动采集 | 必填 | 构建触发时 |
| 完整性 | 文件清单 | 制品内包含的文件及路径 | 打包过程自动生成 | 必填 | 打包完成时 |
| 完整性 | 文件大小 | 制品总体积及关键文件体积 | 打包过程自动生成 | 必填 | 打包完成时 |
| 完整性 | 校验值 | 哈希值，用于验证文件未被替换 | 打包后自动计算 | 必填 | 打包完成时 |
| 依赖与环境 | 依赖清单 | 第三方库及版本锁定信息 | 构建过程自动导出 | 必填 | 构建完成时 |
| 依赖与环境 | 构建环境与工具链版本 | 操作系统、运行时、编译器版本 | 构建环境自动采集 | 必填 | 构建完成时 |
| 质量与状态 | 测试结论 | 关联的测试轮次与通过情况 | 测试系统或人工录入 | 必填 | 测试完成后 |
| 质量与状态 | 评审记录 | 评审人、评审时间与结论 | 评审流程记录 | 必填 | 评审完成时 |
| 质量与状态 | 放行状态 | 待评审、已放行、已拒绝等 | 放行审批人录入 | 必填 | 放行决策时 |
| 流转 | 存放位置 | 制品仓库地址或存储路径 | 入库系统自动记录 | 必填 | 入库时 |
| 流转 | 入库时间 | 制品进入仓库的时间 | 入库系统自动记录 | 必填 | 入库时 |
| 流转 | 责任人 | 对该制品内容负责的人员 | 人工指定 | 必填 | 入库时 |
| 流转 | 变更记录 | 重新打包、替换、撤回等操作记录 | 系统记录加人工说明 | 必填 | 每次变更时 |
| 补充 | 交付说明 | 安装步骤、适用场景等 | 人工录入 | 选填 | 发布前 |
| 补充 | 兼容性说明 | 适用的系统版本与硬件条件 | 人工录入 | 选填 | 发布前 |
例外处理需要提前约定。紧急修复场景下，可以先入库并标记“待补录”，在约定时限内补齐测试结论与评审记录；补录完成前，该制品不得进入对外交付环节。字段取值口径发生变化时，旧记录保留原口径说明，新记录按新口径填写，避免同一字段在不同时期含义不一致。
操作步骤：从字段设计到记录落地的五步
字段清单确定后，需要把它变成构建与发布流程中的固定动作。以下五步按顺序推进，每步都有明确的输入、动作、输出和完成标志。
第一步：梳理交付物类型与追溯场景
输入是团队现有的交付物清单和近半年的发布记录。动作是列出主要交付物类型，逐类标注需要回答的追溯问题，例如“这个安装包对应哪次代码提交”“这个镜像是否经过安全评审”。输出是一份交付物类型与追溯场景对照表。完成标志是每类交付物至少对应一个明确的追溯场景，且场景能落到具体字段上。
第二步：定义字段口径与命名规范
输入是第一步的对照表。动作是逐字段写明含义、格式和取值来源系统，例如版本号采用什么格式、校验值使用哪种哈希算法、构建任务编号从哪个系统获取。输出是字段规范文档初稿。完成标志是每个必填字段都有唯一确定的取值来源，不存在两个系统各记一套的情况。
第三步：确定必填规则与校验方式
输入是字段规范初稿。动作是划分自动采集与人工补录的分工：代码提交、构建任务、校验值、依赖清单由系统自动写入；测试结论、评审意见、放行状态由对应角色人工填写。同时定义校验方式，例如校验值为空时阻止入库、放行状态未填写时阻止发布。输出是带校验规则的字段规范。完成标志是每条必填规则都能在流程中被系统或检查动作拦截。
第四步：在构建或发布环节嵌入记录动作
输入是带校验规则的字段规范。动作是把记录动作挂到构建流水线和发布流程的固定节点上，构建完成即写入来源与完整性字段，发布审批时写入放行状态。输出是嵌入记录动作的流程配置。完成标志是任意一次构建或发布都会产生一条记录，无需事后追补。
第五步：抽样核对与修订
输入是已运行的记录数据。动作是每月抽取一定数量的制品记录，核对字段是否完整、取值是否与实际情况一致，收集填写人的反馈并修订字段规范。输出是抽查记录和字段规范的新版本。完成标志是抽查发现问题有明确整改项，字段规范完成版本更新并通知到相关角色。
记录落地后，字段规范、评审节点与放行状态需要有稳定的承载位置。ONES 当前方案覆盖需求、基线、版本、变更、测试与发布，围绕需求、基线、版本和变更建立统一管理对象，支撑过程状态追踪和交付结果回溯；测试用例、缺陷、版本和发布过程可以关联到需求链路中，便于在出现问题时定位影响范围。团队可以把字段规范作为交付物模板沉淀，把评审与放行作为流程节点执行，使记录动作跟着工作项状态推进，减少事后补录。
角色分工与各环节交付物
记录责任需要落到具体角色和具体时点，否则字段容易在交接处缺失。下表按角色列出主要填写与校验职责，团队可根据规模合并角色，但职责本身不宜省略。
| 角色 | 负责字段 | 时点 | 交付物 |
|---|---|---|---|
| 构建或发布执行人 | 来源类、完整性类字段，确认自动采集结果无误 | 构建完成、入库前 | 构建记录、入库记录 |
| 开发负责人 | 依赖清单、版本口径、兼容性说明 | 构建完成、发布前 | 依赖确认记录 |
| 测试或质量角色 | 测试结论、缺陷关联情况 | 测试轮次结束 | 测试报告 |
| 评审与放行审批人 | 评审记录、放行状态 | 评审会与放行决策时 | 评审结论、放行记录 |
| 配置或发布管理角色 | 字段规范维护、记录完整性抽查、变更记录审核 | 持续，按月抽查 | 字段规范文档、记录模板、抽查记录 |
角色分工确定后，建议把字段规范文档、记录模板和抽查记录作为三份固定交付物管理。字段规范文档说明每个字段的含义与规则，记录模板给出填写结构，抽查记录保留核对结果与整改项。三份交付物都应有版本号，字段调整时同步更新。
示例：一个安装包的元数据记录长什么样
以下为演示情景，展示一条填满的记录如何形成追溯链路，数值与名称为示意，不代表真实项目数据。
| 字段 | 示例值 | 填写方式 |
|---|---|---|
| 制品名称 | 客户端安装包 | 构建配置自动带入 |
| 版本号 | 3.4.1 | 构建任务自动生成 |
| 制品类型 | 安装包 | 构建配置自动带入 |
| 唯一标识 | PKG-20240612-0031 | 系统生成 |
| 代码仓库与提交版本 | client-repo，提交 a1b2c3d | 构建系统自动采集 |
| 构建任务编号 | BUILD-8842 | 构建系统自动采集 |
| 构建时间 | 2024-06-12 14:20 至 14:36 | 构建系统自动采集 |
| 构建执行人 | 发布流水线服务账号 | 构建系统自动采集 |
| 文件清单 | 安装程序、配置文件、说明文档共 12 个文件 | 打包过程自动生成 |
| 文件大小 | 86 MB | 打包过程自动生成 |
| 校验值 | SHA-256 摘要值 | 打包后自动计算 |
| 依赖清单 | 运行时库 4 项，版本已锁定 | 构建过程自动导出 |
| 构建环境与工具链版本 | 指定操作系统版本与打包工具版本 | 构建环境自动采集 |
| 测试结论 | 回归测试通过，遗留 1 个低优先级缺陷已记录 | 测试角色人工填写 |
| 评审记录 | 发布评审会通过，评审人两名 | 评审流程记录 |
| 放行状态 | 已放行 | 放行审批人填写 |
| 存放位置 | 制品仓库指定目录 | 入库系统自动记录 |
| 入库时间 | 2024-06-12 15:02 | 入库系统自动记录 |
| 责任人 | 客户端开发负责人 | 人工指定 |
| 变更记录 | 首次入库，无后续变更 | 系统记录 |
这条记录的追溯链路是：从唯一标识出发，可以找到构建任务 BUILD-8842，再回到代码提交 a1b2c3d；通过校验值可以验证仓库中的文件与构建产物一致；通过测试结论与放行状态可以确认该版本经过质量验证并获批交付。自动采集字段覆盖了来源与完整性，人工填写集中在测试、评审与放行判断上。
迁移到其他交付物类型时，规律相同：镜像类交付物把文件清单替换为镜像层信息与镜像摘要，配置包把依赖清单替换为配置项清单与适用环境范围，文档类交付物则弱化构建字段、强化版本与评审字段。示例的适用边界是常规发布流程，紧急修复场景按前文的例外处理约定执行。
完成检查：记录是否可用的核对项
记录是否达到可用标准，可以按以下清单逐项核对。每项给出通过标准，其中标注为阻断项的条目未通过时，记录不能用于交付审计。
| 核对项 | 通过标准 | 是否阻断 |
|---|---|---|
| 标识唯一性 | 唯一标识在全部记录中不重复，且与存放位置中的制品一一对应 | 是 |
| 来源可回溯 | 能通过记录找到具体代码提交版本与构建任务编号 | 是 |
| 完整性可验证 | 校验值存在且与仓库中文件重新计算的结果一致 | 是 |
| 依赖与环境完整 | 依赖清单与工具链版本可支撑重新构建 | 否 |
| 质量状态明确 | 测试结论有明确通过或带条件通过判断，并关联测试记录 | 是 |
| 放行有结论和责任人 | 放行状态为已放行或已拒绝，审批人可查 | 是 |
| 变更记录可查 | 重新打包、替换、撤回等操作均有记录和说明 | 否 |
| 字段规范有版本 | 字段规范文档带版本号，字段调整有变更说明 | 否 |
缺失来源信息或校验值的记录，无法证明制品与代码的对应关系，也无法验证文件是否被替换，这类记录不能用于交付审计，需要补齐后重新核对。抽查中发现的问题应记入抽查记录，明确整改责任人与完成时限，并在下一次抽查中复核。
常见问题
紧急修复场景下，制品元数据记录可以先入库后补录吗？
可以，但需要提前约定补录时限和限制条件。紧急修复时，允许先入库并标记“待补录”，在约定时限内补齐测试结论与评审记录。补录完成前，该制品不得进入对外交付环节。补录完成后，按正常记录核对完整性，确认追溯链闭合。
不同交付物类型（如镜像、配置包、文档）的字段清单需要完全一致吗？
不需要完全一致。建议先按主要交付物类型各列一份字段草案，再合并成统一规范。统一规范中，标识、来源、完整性、质量与放行状态等保证追溯闭环的字段应保持一致；依赖与环境、文件清单等字段可按交付物类型调整。例如镜像类交付物记录镜像层信息与镜像摘要，配置包记录配置项清单与适用环境范围，文档类交付物弱化构建字段、强化版本与评审字段。
字段取值口径发生变化时，旧记录如何处理？
旧记录保留原口径说明，新记录按新口径填写，避免同一字段在不同时期含义不一致。字段规范文档应带版本号，字段调整时记录变更说明，并通知相关角色。抽查时如发现旧记录因口径变化导致追溯困难，可在变更记录中补充说明，不要求批量重写历史记录。
记录完整性抽查应该多久做一次，抽查哪些内容？
建议按月抽查，抽取一定数量的制品记录，核对字段是否完整、取值是否与实际情况一致。重点核对阻断项：唯一标识是否与存放位置一一对应、能否回溯到具体代码提交与构建任务、校验值是否与仓库文件重新计算的结果一致、测试结论与放行状态是否有明确结论和责任人。抽查发现问题应记入抽查记录，明确整改责任人与完成时限，并在下一次抽查中复核。
团队规模较小，角色分工可以合并吗？
可以合并角色，但职责本身不宜省略。例如构建执行人与开发负责人可由同一人承担，测试与放行审批在小团队中也可能由同一人完成。合并时需确保每个必填字段都有明确的填写责任人和校验动作，避免因角色合并导致记录在交接处缺失。字段规范维护与记录完整性抽查建议保留独立责任，以维持记录口径的一致性。
