3. 指标口径定义：什么是指标口径、口径的构成要素

在工程分析平台中，指标口径是连接原始数据与业务决策的核心契约。它并非简单的计算公式，而是一套完整的、可复用的语义定义与计算规范，确保同一指标在不同数据流水线、不同团队、不同时间点下产出完全一致的结果。

3.1 什么是指标口径

指标口径是对一个量化指标的业务含义、统计范围、计算逻辑与数据来源的正式化描述。它解决了“这个数字到底是怎么算出来的”这一根本问题。没有统一的口径，数据流水线协同将陷入“同名不同义、同义不同数”的混乱局面。

3.2 口径的构成要素

一个完整的指标口径定义由三个核心要素构成：维度、度量与业务规则。三者之间的关系可以通过下图直观理解。

3.3 要素详解

3.3.1 维度 (Dimension)

维度是观察数据的业务视角，决定了指标可以被如何切分与下钻。在口径定义中，维度必须明确其粒度与取值域。

• 粒度： 数据聚合的最小单元，例如“单日”、“单个用户”、“单个订单”。
• 取值域： 维度的合法值范围，例如“国家维度”的取值域为 ISO 3166 国家代码列表。
• 常见维度示例： 时间（日/周/月）、地域（国家/省份/城市）、用户属性（新/老用户）、产品品类。

3.3.2 度量 (Measure)

度量是被计算的数值，是指标的量化主体。度量定义必须包含数据类型、单位与聚合函数。

3.3.3 业务规则 (Business Rule)

业务规则是口径定义中最复杂、最易出错的部分。它规定了数据筛选条件、计算时机与异常处理逻辑。

• 筛选条件： 哪些数据行参与计算。例如“仅统计支付成功且退款金额为0的订单”。
• 计算时机： 数据截止时间点。例如“T+1 凌晨2点基于全量快照计算”。
• 异常处理： 空值、重复值、异常值的处理策略。例如“度量字段为NULL时，该行不参与聚合”。
• 特殊逻辑： 去重规则、分摊规则、汇率转换规则等。

3.4 口径定义示例：GMV（商品交易总额）

以下通过一个完整的 GMV 口径定义，展示三个要素如何协同工作。

3.5 口径定义在流水线中的配置形式

在工程分析平台中，指标口径最终会被序列化为一种可解析的配置格式，供数据流水线引擎读取与执行。以下是一个基于 YAML 的口径配置示例：

# gmw_daily_metric.yaml
metric:
  name: "gmv_daily"
  display_name: "每日商品交易总额"
  version: "1.2.0"

  dimensions:
    - name: "date"
      type: "date"
      granularity: "day"
    - name: "shop_id"
      type: "string"
    - name: "product_id"
      type: "string"

  measure:
    field: "order_amount"
    data_type: "decimal(18,2)"
    unit: "元"
    aggregation: "sum"

  business_rules:
    filters:
      - condition: "order_status = 'paid'"
      - condition: "payment_date >= '2024-01-01'"
    dedup:
      key: "order_id"
      strategy: "keep_first_by_payment_time"
    null_handling: "exclude"
    schedule: "0 3 * * *"