3. 指标口径配置规范总览
指标口径配置规范是保障数据资产从生产到消费全链路一致性的核心契约。本章从核心原则、命名规范、版本管理三个维度构建总览框架，为后续接口调试与平台部署奠定语义基础。
3.1 配置规范的核心原则
指标口径配置需遵循以下四项基本原则，确保定义无歧义、计算可复现、变更可追溯：
| 原则 | 说明 | 违反后果 |
|---|---|---|
| 唯一性 | 每个指标在全局拥有唯一标识（口径ID），禁止同名异义或同义异名 | 数据对账失败，报表口径打架 |
| 可计算性 | 口径定义必须包含明确的原子指标、维度、过滤条件与聚合函数 | ETL 无法解析，下游取数报错 |
| 版本化 | 每次口径变更必须生成新版本，旧版本保留只读快照 | 历史数据无法回溯，归因困难 |
| 可追溯性 | 口径配置需记录变更人、时间、原因及依赖的上游数据源 | 问题排查无入口，审计不通过 |
实践提示： 在平台初始化阶段，建议先完成「原子指标」与「派生指标」的分离配置，再通过组合规则生成复合指标，可大幅降低口径冗余。
3.2 命名规范
命名规范是口径配置的「第一道防线」。统一采用分层三段式结构，避免因命名混乱导致的重复建设与理解偏差。
- 第一段：业务域（如：trade、user、product）—— 使用小写英文缩写，不超过 6 个字符。
- 第二段：原子指标（如：order_amt、login_cnt）—— 使用下划线连接，动词在前、名词在后。
- 第三段：统计粒度（如：d、m、w 表示日/月/周，或维度后缀 _by_store）—— 明确时间周期与聚合维度。
完整示例：trade_order_amt_d（交易域-订单金额-日汇总）、user_login_cnt_m_by_city（用户域-登录次数-月-按城市）。
避坑指南： 禁止在口径名称中使用中文拼音、特殊字符（@、#、空格）或含义模糊的缩写（如 tmp、test、aaa）。平台会自动校验命名格式，不符合规范的口径将无法提交。
3.3 版本管理规范
版本管理采用语义化版本号 + 生命周期状态机模型，确保口径变更过程可管控、可回滚。
| 版本号示例 | 变更类型 | 触发条件 | 兼容性 |
|---|---|---|---|
| v1.0.0 | 初始发布 | 口径首次上线 | — |
| v1.1.0 | 次要变更 | 新增维度、调整过滤条件（不影响结果集语义） | 向前兼容 |
| v2.0.0 | 主要变更 | 修改原子指标、聚合方式或业务口径逻辑 | 不兼容，需通知下游 |
| v1.0.1 | 补丁变更 | 修复口径描述、标签或元数据错误 | 完全兼容 |
每个口径版本在生命周期中经历以下状态流转：
- 草稿（Draft）：配置中，仅创建者可见。
- 待审核（Review）：提交审批，锁定编辑。
- 已发布（Published）：审核通过，可供下游调度使用。
- 已废弃（Deprecated）：标记为不再推荐使用，但保留数据查询能力。
- 已下线（Retired）：彻底移除，仅保留元数据快照。
版本管理最佳实践：
- 每次发布前必须执行「口径比对」操作，自动生成与上一版本的差异报告。
- 已发布的口径不允许直接编辑，必须通过「新建版本」发起变更流程。
- 建议每个口径保留至少最近 3 个活跃版本，历史版本按季度归档至冷存储。