第4章 建立指标口径文档：统一计算规则、数据源与处理逻辑
指标口径文档是产品、算法、工程与数据分析团队之间的“唯一事实来源”。没有统一口径，同一个“DAU”可能在不同看板上差出10%，导致决策混乱。本章将给出建立口径文档的标准化流程，确保所有团队对每个指标的来源、计算方式与边界条件有一致理解。
常见陷阱：很多团队在指标上线后才补口径文档，或仅在口头对齐。这种非正式做法会在版本迭代、人员变动时引入灾难性不一致。文档必须在指标对齐阶段同步生成。
4.1 适用场景
- 新产品或新功能的核心指标首次定义时
- 已有指标因业务逻辑变更需要重新对齐口径
- 跨团队（产品、推荐、广告、数据工程）联合看板建立前
- 模型效果监控指标与业务指标做第一次映射时
4.2 前置条件
| 条件 | 说明 | 责任人 |
|---|---|---|
| 指标清单初稿 | 包含指标名称、业务含义、期望数值范围 | 产品经理 |
| 数据源目录 | 各可用数据表的名称、存储位置、更新时间戳字段 | 数据工程师 |
| 模型输出schema | 模型推理结果的字段列表、类型、示例值 | 算法工程师 |
| 历史异常案例 | 过去采用的计算口径引起争议或错误的记录 | 数据分析师 |
4.3 操作步骤
- 步骤一：填充指标基础信息 —— 为每个指标填写唯一ID、中文全称、业务定义和计算公式的数学表达式。
- 步骤二：明确数据源与字段映射 —— 指定原始表的名称、分区键、主键字段以及提取该指标所需的全部字段名。
- 步骤三：定义聚合方式与时间窗口 —— 确定聚合粒度（如用户级/会话级/事件级）、聚合函数（SUM/COUNT/DISTINCT COUNT/AVG/PERCENTILE）以及窗口范围（自然日/滑动24h/周同比）。
- 步骤四：写入异常值处理规则 —— 列出哪些数值视为异常（如null、负值、超过3σ的离群点），并指定处理方案（剔除/替换为均值/标记-1）。
- 步骤五：关联模型输出字段 —— 若该指标由模型推理产生，需填写模型名称、版本、输出字段及打标逻辑。
- 步骤六：评审并锁定版本 —— 召集产品、算法、数据三方会审，通过后锁定文档版本，编辑权限仅开放给数据负责人。
最佳实践：对每个指标使用唯一“指标ID”（如
METRIC_CTR_V1），不得重名。在后续模型监控看板、A/B实验分析、周报中统一引用该ID，避免口头命名造成混淆。
4.4 输入输出物
| 类型 | 内容 | 形式 |
|---|---|---|
| 输入 | 指标清单初稿、数据源目录、模型输出schema、历史异常案例 | Markdown/Excel/内部Wiki |
| 输出 | 指标口径文档 v1.0（含计算规则、数据源、聚合方式、时间窗口、异常处理规则） | 版本化Markdown文档，存放于共享知识库 |
4.5 责任边界
- 产品经理： 负责提供指标的业务定义和期望计算逻辑，对业务正确性负责。
- 算法工程师： 负责填写模型侧输出字段及打标规则，保证模型结果可复现。
- 数据工程师 / 数据产品经理： 负责审核数据源的可用性、字段类型匹配、聚合性能，并录入文档。
- 数据分析师： 作为最终验收方，交叉验证口径文档中的计算脚本产出是否与手算示例一致。
4.6 记录材料
- 口径文档本体： 按上述步骤填充的Markdown文件，存储于团队共享Wiki（如Confluence/语雀），路径统一为
/产品中心/指标口径/产品名_版本号.md。 - 变更日志： 每次修改附带变更单，包含变更日期、变更原因、前后对比、审批人。
- 交叉校验脚本： 数据分析师编写的SQL/Python验证脚本，用于抽查口径文档中定义的指标是否能在数据仓库中正确产出。
4.7 异常处理
| 异常场景 | 处理动作 | 输出物 |
|---|---|---|
| 字段在数据源中不存在 | 标记为“待数据采集”，暂时使用代理字段计算，并在文档中注明口径偏差 | 代理字段映射说明 |
| 同一个指标产品与算法定义不一致 | 上升至三方会审，以业务决策为准；若无法调和，分裂为两个指标ID（产品CTR / 模型CTR） | 指标分裂申请单 |
| 聚合窗口时长导致性能过慢 | 采用预聚合表 + 时间窗口下推，文档中注明预聚合表的刷新周期和延迟容忍度 | 预聚合表设计说明 |
4.8 验收标准
- 每个指标均包含完整的计算规则、数据源、聚合方式、时间窗口、异常处理规则五项内容，缺一不可。
- 文档中至少包含1个手算示例：给定原始数据样本，按照文档中的规则手动推导出指标值，且该值与实际跑数脚本结果一致。
- 产品、算法、数据三方责任人在文档尾部签署确认，记录签字版本与日期。
- 文档已上传至共享知识库，且文件夹权限设置为“仅数据负责人可编辑”，其他成员为只读。
典型输出示例（CTR指标口径文档片段）：
## 指标ID: METRIC_CTR_V2
### 1. 计算规则
CTR = 模型推荐总点击次数 / 模型推荐总展示次数
（点击定义为用户点击后进入落地页的事件，若点击后秒退不计入）
### 2. 数据源 & 字段映射
- 原始表: bi.dwd_recommend_event (日分区表，分区键 dt)
- 展示事件: event_type = 'show'
- 点击事件: event_type = 'click' AND page_load_time >= 2s
### 3. 聚合方式
- 粒度: 用户ID + 日期
- 聚合: SUM(click_flag) / SUM(show_flag)，最终输出浮点数百分比
### 4. 时间窗口
自然日 (00:00:00 ~ 23:59:59)，以事件发生时间戳为准
### 5. 异常值处理
- 排除展示次数为0的天（分母为0）
- 排除CTR > 1.0的记录（数据异常标记为-1，不参与汇总计算）