第4章 指标口径定义规范

指标口径是数据从原始业务日志到看板数值之间的转换规则。同一个指标名（如“支付成功率”）在不同团队、不同版本间可能对应完全不同的计算逻辑，导致看板数据打架、复盘结论失焦。本章给出可落地的口径定义三要素、命名规则与版本管理方案，确保指标可追溯、可复算、可比较。

4.1 口径三要素

任何一个业务指标口径，必须同时声明以下三个要素，缺一不可：

要素	定义	常见选项示例	易错点
聚合方式	对原始数据执行的数学或统计运算	SUM / COUNT / DISTINCT COUNT / AVG / P50 / P95 / RATE	忽略去重规则（如 COUNT vs COUNT DISTINCT）
时间窗	指标计算的观测时间段	自然日 / 滚动24h / 自然周 / 自然月 / 近7日 / 近30日	自然日 vs 业务日（如交易截止到凌晨2点）未区分
实体范围	指标适用的业务主体或限定条件	全部用户 / 新用户 / 付费用户 / 国内 / 仅iOS / 剔除内部测试	范围叠加时逻辑歧义（如“新用户”的时间定义）

4.2 完整口径示例

以“支付成功率”为例，不同团队定义的差异：

口径A（交易团队）：
  聚合方式：SUM(支付成功订单数) / SUM(发起支付订单数)
  时间窗：自然日（00:00:00–23:59:59，UTC+8）
  实体范围：全量真实用户（剔除内部测试账号ID列表 v4.2）

口径B（财务团队）：
  聚合方式：COUNT DISTINCT(支付成功user_id) / COUNT DISTINCT(发起支付user_id)
  时间窗：业务日（前日06:00:00–当日05:59:59，UTC+8）
  实体范围：已实名认证用户（剔除退款订单对应user_id）

两个口径虽然都叫“支付成功率”，但聚合方式、时间窗、实体范围全部不同，不可直接对比。这就是口径三要素必须显式声明的根本原因。

4.3 命名规则

指标命名的目标是“见名知义”，避免歧义和冗余。推荐采用三级命名结构：

• 一级（业务域）：支付 / 交易 / 用户 / 内容 / 广告
• 二级（原子指标或维度）：成功 / 发起 / 退款 / 活跃 / 曝光
• 三级（聚合/限定）：率 / 数 / 人均 / 次均 / 日 / 月

禁止行为：

• 在指标名中嵌入版本号（如“支付成功率_v3”），版本信息应放在元数据字段中；
• 使用拼音缩写或团队内部黑话（如“zfl”代表支付率）；
• 命名中同时出现语义重叠的词（如“每日日均支付成功数”）。

4.4 版本管理

指标口径会随业务迭代而调整。没有版本管理的口径体系会在三个月后彻底失控。建议采用语义化版本 + 变更日志机制：

版本号	变更类型	说明	示例
MAJOR	不兼容变更	聚合方式变更 / 实体范围缩减或扩展超过20% / 时间窗类型变更	自然日→滚动24h
MINOR	兼容性增强	新增过滤条件但数值变化 <5% / 时间窗偏移调整	UTC+8→UTC+9
PATCH	修正性变更	修复代码bug / 修正文档描述 / 补充排除名单	更正内部测试账号ID列表

4.5 口径三要素与命名版本关系图

4.6 口径变更流程

当业务方提出指标口径调整时，必须走以下审批与记录流程：

1. 提出变更申请：说明变更原因、预期影响范围、新旧口径差异对比；
2. 数据团队评估：量化影响（数值偏差百分比、涉及历史数据范围、下游看板影响数）；
3. 版本号升级：按语义化版本规则确定 MAJOR / MINOR / PATCH；
4. 全量元数据更新：指标字典、ETL 调度、看板数据源同时生效，旧版本标为“已弃用-保留可查”；
5. 发布变更公告：在数据门户/指标集市中通知所有消费方，附迁移指引。

4.7 业务动作与复盘分析

口径规范直接影响看板数据的可信度。当看板出现异常波动时，第一步不是排查数据管道，而是确认口径是否发生过未记录的变更：

• 对比当前指标版本号与基期版本号是否一致；
• 检查聚合方式、时间窗、实体范围三个维度是否有隐性漂移；
• 验证命名是否在跨团队协作中被复用或覆盖。