3. 口径定义规范：标准口径文档的构成要素与编写模板

标签口径不一致的根源，往往不在于“算错了”，而在于“没写清楚”。一份缺失上下文、缺少边界条件、缺乏版本控制的口径文档，会在跨团队协作中迅速演变为数据沼泽。本节将拆解标准口径文档的必备构成要素，并给出可直接复用的编写模板。

3.1 标准口径文档的构成要素

一个完整的标签口径定义文档，应包含以下 7 个核心模块。缺少任何一个，都可能成为未来口径不一致的隐患。

3.2 口径逻辑的标准化表达

口径逻辑是文档的核心。建议采用“三段式”结构来编写，确保逻辑无歧义：

1. 数据源声明：明确表名、分区字段、过滤条件（如只取状态为“已完成”的订单）。
2. 计算规则：用伪代码或 SQL 片段描述核心计算逻辑，避免自然语言带来的歧义。
3. 后处理规则：空值填充、异常值截断、单位换算、四舍五入规则等。

以下是一个“用户近 30 天消费金额”标签的口径逻辑示例：

-- 标签编码：TAG_USER_AMT_30D
-- 口径版本：v2.1

-- 1. 数据源
--   表：dwd.trade_order_di (分区：dt)
--   过滤：order_status = 'FINISHED' AND is_test_order = 0

-- 2. 计算规则
WITH user_amt AS (
  SELECT
    user_id,
    SUM(actual_amount) AS total_amt
  FROM dwd.trade_order_di
  WHERE dt BETWEEN DATE_SUB(CURRENT_DATE(), 29) AND CURRENT_DATE()
    AND order_status = 'FINISHED'
    AND is_test_order = 0
  GROUP BY user_id
)

-- 3. 后处理规则
--    空值填充为 0.00
--    金额保留两位小数，四舍五入
SELECT
  user_id,
  ROUND(COALESCE(total_amt, 0.00), 2) AS tag_value
FROM user_amt;

3.3 标准口径文档编写模板

以下是一个可直接复用的标准口径文档模板。建议团队将其固化到 Wiki 或文档管理系统中，作为新建标签的默认模板。

# 标签口径定义文档

## 1. 标签元信息
- 标签名称：[填写]
- 标签编码：[填写]
- 所属主题域：[用户/商品/交易/营销/风控]
- 业务负责人：[姓名/团队]
- 技术负责人：[姓名/团队]
- 创建日期：[YYYY-MM-DD]
- 最后修改日期：[YYYY-MM-DD]
- 当前版本号：[vX.Y]

## 2. 业务定义
- 业务语义：[用一句话说清楚这个标签代表什么]
- 适用场景：[哪些业务分析或模型会用到]
- 不适用场景：[哪些场景下该标签无意义或不应使用]

## 3. 口径逻辑
### 3.1 数据源
- 源表：[数据库.表名]
- 分区字段：[如 dt]
- 数据范围：[如近 30 天、全量]
- 过滤条件：[如只取状态为 X 的记录]

### 3.2 计算规则
[此处粘贴伪代码或 SQL，见 3.2 节示例]

### 3.3 后处理规则
- 空值处理：[填充为 0 / 保留空值 / 剔除]
- 异常值处理：[如超过 3 倍标准差则截断]
- 精度处理：[保留几位小数，如何舍入]

## 4. 边界条件
- 计入场景：[明确列出]
- 排除场景：[明确列出]
- 特殊场景处理：[如退款订单、测试账号、内部员工等]

## 5. 版本变更记录
| 版本 | 日期 | 变更人 | 变更原因 | 变更内容 | 影响范围 |
|------|------|--------|----------|----------|----------|
| v1.0 | 2024-01-01 | 张三 | 初始创建 | - | - |
| v2.0 | 2024-06-01 | 李四 | 业务规则调整 | 时间窗口由 30 天改为 90 天 | 影响 3 个报表 |

## 6. 质量监控规则
- 期望值范围：[最小值 ~ 最大值]
- 波动阈值：[日环比波动不超过 X%]
- 空值率上限：[不超过 X%]
- 一致性校验：[与口径相同的其他标签交叉验证]

## 7. 下游消费清单
- 数据产品：[产品名称 / 链接]
- 报表：[报表名称 / 链接]
- 模型：[模型名称 / 负责人]
- API：[接口名称 / 调用方]

3.4 口径文档的版本管理策略

口径文档必须与代码同步管理。推荐以下策略：

• 文档即代码：将口径文档以 Markdown 格式存放在代码仓库中，与 ETL 脚本同目录、同分支、同版本。
• 变更即评审：口径变更必须走 MR/PR 流程，由业务负责人和技术负责人共同评审。
• 版本号对齐：口径文档版本号与标签计算脚本版本号保持一致，方便追溯。

下图展示了口径文档与代码的协同管理流程：

3.5 口径文档的常见质量缺陷

在实际数据治理工作中，我们发现以下 5 类缺陷最容易导致口径不一致。建议在文档评审时重点检查：