4. 元数据规范总览

归档包元数据规范是确保审查意见与变更记录可追溯、可解析、可长期保存的基础。本章从字段定义、命名规则、数据类型与约束条件三个维度，系统梳理核心元数据字段体系，为后续的测试验证提供精确的契约依据。

4.1 核心元数据字段定义

元数据字段分为基础标识层、内容描述层、审查追溯层与变更记录层四个层级，共计 12 个必选字段与 6 个可选字段。下表列出各字段的名称、语义与层级归属。

4.2 字段命名规则

字段命名遵循以下三条硬性规则，以保证跨系统解析的一致性：

• 小写蛇形命名法：所有字段名使用小写字母，单词之间以下划线分隔。例如 review_stage、change_type。
• 禁止缩写歧义：除业界通用缩写（如 id、uuid）外，禁止使用自定义缩写。例如 rev_stg 不合法，必须写为 review_stage。
• 层级前缀可选：为提升可读性，允许在字段名前添加层级前缀缩写，但非强制。例如 base_package_id 或直接 package_id 均可接受。

# 合法命名
package_id
review_stage
change_summary
affected_components

# 非法命名
PackageID        # 大写字母
reviewStage      # 驼峰命名
chg_sum          # 自定义缩写
affectedComps    # 驼峰 + 缩写

4.3 数据类型与约束条件

每个字段均绑定严格的数据类型与约束条件，约束条件包括长度限制、枚举值范围、格式正则与空值策略。下表列出关键字段的完整约束定义。

4.4 元数据字段关系结构图

下图展示四个层级之间的依赖关系与数据流向。基础标识层为根节点，内容描述层与审查追溯层并列依赖基础标识层，变更记录层可独立存在但推荐关联基础标识层。

4.5 元数据字段约束验证流程

在归档包生成与解析过程中，约束验证按以下顺序执行，确保元数据在进入存储层之前即被清洗为合规状态。

1. 结构验证：检查 JSON 结构完整性，确认所有必选字段存在且类型正确。
2. 格式验证：对 string 类型字段执行正则匹配，对 datetime 字段执行格式解析。
3. 枚举验证：检查 enum 字段值是否在允许值列表中，大小写敏感。
4. 长度验证：检查 string 与 array 字段的长度是否在约束范围内。
5. 空值策略验证：对禁止空值的字段检查 null 与缺失情况。

通过上述字段定义、命名规则、数据类型与约束条件的系统化设计，元数据规范具备了机器可读、可验证、可扩展的特性，为后续的审查意见与变更记录测试验证提供了精确的契约基础。