BI 指标平台案例：先统一口径，再做漂亮报表

# ✅ 好的做法：指标定义结构化，口径透明可追溯
metrics:
  - name: gmv
    display_name: 商品交易总额
    description: |
      统计周期内所有已支付订单的商品总金额，
      不含运费、不含退款、不含内部测试订单。
    formula: SUM(order_amount)
    source: dw.dwd_order_paid
    filters:
      - order_status IN ('paid', 'shipped', 'completed')
      - is_test_order = false
    grain: [date, shop_id, category_id]
    owner: sales_vp
    tech_owner: data_engineer_lead
    refresh: daily_0600
    version: '2.3'

-- ❌ 坏的做法：GMV 散落在各个看板 SQL 里，口径无人知道
-- 销售部看板 query
SELECT SUM(order_amount) AS gmv  -- 没过滤状态，未支付也算进去了
FROM raw.orders
WHERE created_at >= '2026-06-01'
 
-- 财务部另一个看板 query
SELECT SUM(pay_amount) AS gmv  -- 用了 pay_amount 不是 order_amount
FROM finance.payment_records
WHERE pay_status = 'success'  -- 只算已支付
 
-- 运营部又一套逻辑
SELECT SUM(order_amount) AS gmv
FROM dw.order_detail
WHERE ship_time IS NOT NULL  -- 只算已发货
  AND is_test = 0

# ❌ 坏的做法：指标只有名字，没有口径、没有负责人
metrics:
  - name: gmv
    type: number
    # 没有计算公式
    # 没有数据来源
    # 没有负责人
    # 没有过滤条件

# ✅ 好的做法：血缘关系声明式注册，变更自动发现
# lineage_registry.yaml
lineage:
  - source: kafka.raw_events
    target: flink.dau_realtime_agg
    transform: flink_job_dau_v2
    transform_type: aggregation
    sla: realtime
    quality_level: critical
    owner: data_platform_team
    downstream_alert:
      - channel: slack
        target: "#data-incidents"
 
  - source: flink.dau_realtime_agg
    target: hive.dws_user_active_daily
    transform: hive_insert_overwrite
    transform_type: batch_load
    sla: daily_0600
    quality_level: critical
    owner: data_warehouse_team

# ❌ 坏的做法：血缘关系只存在于某个人的脑子里
# 没人知道 dau 指标的上游是哪个 Flink 任务
# 也没人知道改了埋点格式会影响哪些看板
 
# 排障时的对话通常是这样的：
# 「这个指标谁建的？」
# 「好像是去年离职的 XX 建的...」
# 「那上游表是哪个？」
# 「我去看看 SQL 里 from 的是哪张表...」

-- ✅ 好的做法：在 ETL 任务里标注血缘元信息，方便自动采集
-- dws_user_active_daily.sql
-- @lineage.source: ods.user_event_log
-- @lineage.transform: flink_job_dau_v2 -> hive_insert_overwrite
-- @lineage.owner: data_warehouse_team
-- @lineage.quality: critical
-- @lineage.sla: daily_0600
INSERT OVERWRITE TABLE dws_user_active_daily
SELECT
    dt,
    COUNT(DISTINCT user_id) AS dau
FROM ods.user_event_log
WHERE dt = '${bizdate}'
  AND event_type = 'app_open'
GROUP BY dt

-- ❌ 坏的做法：SQL 里没有任何元信息，全靠人肉追溯
-- 改了字段名或者上游表换了，下游没人知道
INSERT OVERWRITE TABLE dws_user_active_daily
SELECT dt, COUNT(1)  -- COUNT(1) 和 COUNT(DISTINCT user_id) 差别巨大
FROM some_table      -- 表名模糊，不知道具体是哪个 schema
WHERE dt = '${bizdate}'
GROUP BY dt
-- 没有注释说明这个指标的业务含义
-- 没有说明 COUNT(1) 是否去重了

# ✅ 好的做法：权限分级，核心指标不可随意修改
METRIC_PERMISSIONS = {
    'core': {
        'can_create': False,       # 不允许新建核心指标
        'can_modify_definition': False,  # 不允许修改口径
        'can_modify_filter': False,      # 不允许修改过滤条件
        'can_use_in_dashboard': True,    # 可以用于看板
        'can_export': True,              # 可以导出数据
        'require_approval': True,        # 变更需要审批
        'query_tier': 'precomputed',     # 走预计算层
    },
    'department': {
        'can_create': True,
        'can_modify_definition': 'owner_only',
        'can_modify_filter': True,
        'can_use_in_dashboard': True,
        'can_export': True,
        'require_approval': 'team_review',
        'query_tier': 'aggregated',
    },
    'experimental': {
        'can_create': True,
        'can_modify_definition': True,
        'can_modify_filter': True,
        'can_use_in_dashboard': False,   # 不出现在公司看板
        'can_export': True,
        'require_approval': False,
        'query_tier': 'isolated_engine', # 走独立查询引擎
        'must_label': '🧪 实验指标',
    },
}

# ❌ 坏的做法：所有人对所有指标有相同权限
# 任何人改了一个核心指标的定义，所有用到它的看板都跟着变
METRIC_PERMISSIONS = {
    'default': {
        'can_create': True,
        'can_modify_definition': True,   # 谁都能改口径
        'can_modify_filter': True,
        'can_use_in_dashboard': True,
        'can_export': True,
        'require_approval': False,       # 没有审批流程
        'query_tier': 'default',         # 所有人都查同一层
    },
    # 结果：7 个版本的留存率、3 个版本的 GMV
    # 没人知道哪个是准的
}

# ✅ 好的做法：刷新周期与数据 SLA 绑定
refresh_policies:
  - metric: daily_active_users
    source_sla: daily_0600       # 源数据每天 6 点更新
    allowed_refresh:
      - daily_0700               # 7 点刷新，保证数据就绪
      - daily_1200               # 中午再看一次，覆盖上午的修正
    max_query_timeout: 30s
    query_tier: precomputed
    auto_disable_if_source_delayed: true  # 源数据延迟时自动禁用刷新
 
  - metric: realtime_gmv
    source_sla: streaming        # 实时流
    allowed_refresh:
      - every_5min
      - every_15min
    max_query_timeout: 10s
    query_tier: realtime
    resource_quota:
      max_concurrent_queries: 50
      max_scan_rows_per_query: 1_000_000

# ❌ 坏的做法：刷新周期随意设置，不看数据 SLA
refresh_policies:
  - metric: monthly_revenue
    refresh: every_5min          # 月数据每 5 分钟刷新？
    query_tier: detail           # 直接查明细表
    # 没有任何资源限制
    # 结果：数据仓库每天被这个看板扫几十亿行
    # 其他报表全部排队等待