跳到主要内容

供数规范

本文档定义数据中台对分析平台、BI、客服后台、运营后台等下游系统的正式供数方式。

1. 适用范围​

本规范适用于以下下游：

  • 分析平台
  • BI / 报表系统
  • 客服后台
  • 运营后台
  • 其他经授权的内部系统

目标：

  • 统一下游取数对象
  • 统一字段和增量规则
  • 让下游数据契约完全独立于 TLog
  • 避免下游直接依赖物理表实现细节

2. 供数总原则​

  1. 业务侧可继续使用 TLog 接入。
  2. 数据进入数据中台后，中心侧统一标准化为 Event 模型。
  3. 下游数据契约与 TLog 无关。
  4. 下游不应默认直接依赖 dc_tlog_* 兼容表。
  5. 正式供数以 dataset 为单位，而不是以“某张物理表”口头约定。

3. 下游取数分层​

3.1 标准事件层​

适用对象：

  • 分析平台
  • BI / 自助分析
  • 通用事件导出

推荐物理模型：

dc_events_{game_id}_{region}

推荐逻辑数据集：

  • dataset_standard_events
  • dataset_login_events
  • dataset_charge_events

3.2 领域事实层​

适用对象：

  • 客服后台
  • 运营后台
  • 固定报表
  • 订单、角色、充值等业务查询

推荐逻辑数据集：

  • dataset_charge_orders
  • dataset_role_profiles
  • dataset_login_facts
  • dataset_item_change_facts

3.3 原始层​

适用对象：

  • 审计
  • 数据排障
  • 重放 / 补数

不作为常规下游供数入口。

4. 标准供数数据集​

4.1 dataset_standard_events​

用途：

  • 通用事件分析
  • 分析平台、BI 的主数据源

建议字段：

  • project_id
  • game_id
  • region
  • zone_id
  • event_name
  • event_time
  • ingest_time
  • source
  • role_id
  • account_id
  • device_id
  • event_uuid
  • properties

主键建议：

  • event_uuid
  • 若上游无稳定 UUID，则使用 (game_id, region, source, raw_ref, row_no) 类组合键在内部生成

时间字段：

  • 业务时间：event_time
  • 入库时间：ingest_time

增量字段：

  • 默认：ingest_time
  • 特殊场景可按 (ingest_time, event_uuid) 做双字段游标

适用方式：

  • SQL / Cube 查询
  • 增量拉取
  • 批量导出

4.2 dataset_login_events​

用途：

  • 登录行为分析
  • DAU / 留存相关下游建模输入

定义：

  • 来源于 dataset_standard_events
  • 过滤条件：event_name = 'loginlog'

关键字段：

  • game_id
  • region
  • zone_id
  • event_time
  • role_id
  • account_id
  • device_id
  • channel
  • platform

4.3 dataset_charge_orders​

用途：

  • 客服订单查询
  • 充值对账
  • 收入报表

来源：

  • 推荐来自领域事实层，而不是直接扫标准事件层

关键字段建议：

  • order_id
  • game_id
  • region
  • zone_id
  • role_id
  • account_id
  • amount
  • currency
  • pay_channel
  • order_status
  • pay_time
  • ingest_time

4.4 dataset_role_profiles​

用途：

  • 客服查角色
  • 中后台角色画像
  • 基础维度服务

来源：

  • 推荐来自维度快照或事实层聚合结果

关键字段建议：

  • game_id
  • region
  • zone_id
  • role_id
  • account_id
  • role_name
  • role_level
  • create_time
  • last_login_time
  • server_state

5. 分析平台接入规范​

分析平台推荐接入 dataset_standard_events 或其事件子集。

推荐方式：

  1. 数据中台提供标准事件数据集
  2. 分析平台按 event_name 映射分析事件
  3. 分析平台增量消费 ingest_time
  4. 分析平台端只面向标准事件字段，不感知上游接入协议

建议字段映射：

  • event_name -> 分析平台事件名
  • event_time -> 事件发生时间
  • account_id / role_id -> 用户主标识
  • device_id -> 设备标识
  • properties -> 事件属性

不建议：

  • 让分析平台直接解析 TLog 文件
  • 让分析平台直接依赖 dc_tlog_* 兼容表
  • 让分析平台自行推断字段映射规则
  • 让下游事件名语义直接绑定 TLog 表名

6. BI 接入规范​

BI 工具推荐通过以下两类方式接入：

  • Cube / SQL API 查询标准事件层
  • 读取预定义 dataset 或导出文件

适合 BI 的数据集：

  • dataset_standard_events
  • dataset_login_events
  • dataset_charge_orders

BI 接入要求：

  • 必须带时间范围
  • 建议带 game_id / region / event_name 过滤
  • 不允许依赖原始字段顺序

7. 客服后台接入规范​

客服后台不应直接扫海量事件明细。

推荐：

  • 优先读取事实层和维度层
  • 按角色、订单、充值、登录摘要等数据集接入

适合客服的数据集：

  • dataset_charge_orders
  • dataset_role_profiles
  • dataset_login_facts

不推荐：

  • 直接读取 dataset_standard_events 做高频在线查询

8. 增量同步规范​

默认增量规则：

  • 使用 ingest_time 作为增量水位

推荐拉取条件：

WHERE ingest_time > :last_watermark
   OR (ingest_time = :last_watermark AND event_uuid > :last_event_uuid)

原因：

  • event_time 可能是历史补数
  • ingest_time 更适合作为同步游标

补数场景要求：

  • 下游必须接受“旧 event_time、较新 ingest_time”的数据
  • 下游不得假设 event_time 单调递增

9. 导出规范​

批量导出建议至少包含：

  • dataset 名称
  • 导出时间范围
  • 导出生成时间
  • 数据版本
  • 字段清单
  • 过滤条件

推荐导出格式：

  • parquet
  • csv
  • jsonl

推荐目录或对象路径语义：

/{dataset}/{game_id}/{region}/{dt=YYYY-MM-DD}/part-*.parquet

10. 权限规范​

下游权限必须最小化，不应默认拥有全量全业务访问权限。

推荐控制维度：

  • project_id
  • game_id
  • region
  • dataset
  • 时间范围

权限示例：

  • 分析平台 A：仅可读 dataset_standard_events 的 game_a/region_a
  • 客服后台 B：仅可读 dataset_charge_orders 和 dataset_role_profiles
  • BI 团队：可读多个 dataset，但必须按项目和业务隔离

11. 不兼容变更规范​

以下变更视为供数协议变更：

  • dataset 字段删除或重命名
  • 主键变更
  • 增量字段变更
  • 时间字段含义变更
  • 事件名语义变更

处理要求：

  1. 先公告
  2. 给迁移窗口
  3. 必要时保留双版本 dataset
  4. 禁止静默破坏下游

12. 一句话约束​

对外供数的正式边界应当是：

下游读取 dataset，下游数据契约不与 TLog 绑定，也不与内部兼容表绑定。

加载评论中...