4. 口径管理元数据模型：口径元数据表结构、版本控制、血缘关系建模
口径管理元数据模型是工程分析平台中连接“业务语义”与“技术实现”的核心骨架。它通过标准化的表结构、严谨的版本控制机制以及精细的血缘关系建模，确保指标口径在定义、变更、追溯和复用过程中的一致性、可审计性与可理解性。本节将深入剖析这三个核心组成部分的设计原理与工程实践。
4.1 口径元数据表结构设计
口径元数据表结构需要承载从业务定义到技术映射的全链路信息。一个健壮的设计通常包含以下核心实体及其关系：
| 实体表 | 核心字段 | 职责描述 |
|---|---|---|
| 口径定义表 | 口径ID、口径名称、业务域、口径类型（原子/派生）、业务定义、计算逻辑、负责人、创建时间、生效状态 | 记录口径的业务语义和计算规则，是元数据模型的核心入口。 |
| 口径版本表 | 版本ID、口径ID、版本号、变更描述、口径定义快照、审批状态、发布人、发布时间、过期时间 | 管理口径的每一次变更历史，支持版本回溯与对比。 |
| 口径-字段映射表 | 映射ID、口径ID、版本ID、数据源ID、表名、字段名、转换逻辑、映射类型（直接/计算/聚合） | 将口径定义映射到具体物理表的字段，实现语义到技术的桥接。 |
| 口径依赖关系表 | 依赖ID、上游口径ID、下游口径ID、依赖类型（强/弱）、依赖层级、生效版本范围 | 记录口径之间的派生与引用关系，是血缘分析的基础。 |
| 口径标签表 | 标签ID、口径ID、标签键、标签值、标签类型（系统/自定义） | 提供灵活的维度扩展，用于口径的分类、分级与搜索。 |
设计要点： 口径定义表与口径版本表采用“主表+历史表”模式，避免在定义表上直接更新，确保每次变更都生成一条不可变的版本记录。口径-字段映射表支持多数据源映射，是平台实现“口径一次定义，多源复用”的关键。
4.2 版本控制机制
口径的版本控制需要解决“变更可追溯、版本可对比、发布可管控”三大问题。推荐采用基于语义化版本（Semantic Versioning）的扩展策略：
- 主版本号（Major）： 业务语义发生重大变更，导致基于旧口径的计算结果不可直接对比时递增。例如：统计口径从“当日下单用户”变更为“当日支付成功用户”。
- 次版本号（Minor）： 业务语义不变，但计算逻辑或数据源发生调整，可能影响结果精度时递增。例如：从“全量数据计算”变更为“剔除测试数据后的计算”。
- 修订号（Patch）： 仅修复文档错误、优化性能或修正非功能性缺陷，不影响计算结果时递增。
版本控制的生命周期状态机如下：
版本对比策略： 在口径版本表中存储“口径定义快照”（JSON格式），包含完整的计算逻辑、映射关系和依赖列表。当需要对比两个版本时，直接加载快照进行结构化差异分析，避免关联多张表带来的性能开销和一致性问题。
4.3 血缘关系建模
口径血缘关系建模旨在构建从“业务指标”到“原始数据字段”的完整追溯链路。模型需要支持正向推导（口径依赖了哪些字段）和反向追溯（某个字段被哪些口径使用）。
血缘关系模型采用分层架构：
- 业务血缘层： 记录口径与口径之间的派生关系。例如：口径A（客单价）= 口径B（总成交额） / 口径C（成交用户数）。
- 技术血缘层： 记录口径与物理字段之间的映射关系。例如：口径B（总成交额）映射到 dwd_sales 表的 amount 字段，经过 sum 聚合。
- 数据流水线血缘层： 记录字段在ETL过程中的流转关系。例如：ods_sales.amount → dwd_sales.amount，经过清洗和类型转换。
血缘关系的存储模型设计如下：
血缘建模避坑指南： 避免在血缘关系表中直接存储全路径字符串（如“口径A→口径B→字段X”），这会导致更新和查询异常复杂。推荐采用“边表”模型，每条记录只存储直接上下游关系，通过递归查询或图数据库引擎实现全链路追溯。同时，务必在血缘关系表中记录“生效版本范围”，防止血缘链路跨越已废弃的版本。
4.4 元数据模型与流水线的协同
口径元数据模型需要与数据流水线深度集成，实现“定义即配置，变更即感知”：
- 自动血缘采集： 数据流水线在执行过程中，自动解析SQL或ETL脚本，将字段级别的输入输出关系写入血缘关系表。
- 口径影响分析： 当底层字段发生变更时，通过血缘关系表反向追溯所有受影响的口径，自动触发版本更新流程。
- 口径验证自动化： 流水线在发布前，自动校验当前口径版本与所依赖字段的兼容性，防止因字段删除或类型变更导致的口径计算失败。
工程实践建议： 在口径-字段映射表中增加“校验规则”字段（如：字段类型必须为DECIMAL(18,2)、字段不允许为NULL等）。数据流水线在每次调度前，先执行校验规则，只有通过校验的口径版本才能进入计算阶段。这将在后续章节《口径验证规则配置》中详细展开。