2 行
58 KiB
Markdown
2 行
58 KiB
Markdown
|
# TDD-10 数据埋点与分析设计\n\n> 文档类型：技术设计文档（Technical Design Document）\n> 版本：1.0\n> 日期：2026-07-02\n> 关联文档：TDD-04《数据库表结构设计》、TDD-05《API接口设计》、TDD-06《离线挂机结算系统设计》、TDD-07《反作弊与安全设计》、TDD-08《GM与运营后台设计》、PRD-01《核心玩法与系统需求文档》、PRD-03《热更新与活动系统需求文档》、GDD-06《经济系统设计》、GDD-22《开放世界随机事件与玩家可交互内容层》\n\n---\n\n## 1. 文档信息\n\n| 项目 | 说明 |\n|------|------|\n| 目标 | 为《洪荒大陆》挂机手游定义数据埋点事件规范、数据管道架构、核心分析指标、A/B测试框架、数据看板及数据安全合规方案。 |\n| 读者 | 数据工程师、服务端开发（Nakama/Go）、客户端开发（Cocos Creator 3.x）、数值策划、运营 |\n| 技术栈 | 客户端 Cocos Creator 3.x；服务端 Nakama 3.x + Go 插件 + PostgreSQL 16 + Valkey + Nacos 2.x；数据管道 Kafka + Flink + ClickHouse + Hive/Spark |\n| 核心约束 | 无任务系统、无赛季重置、概率/机遇驱动、全自动ATB即时制战斗 |\n| 境界体系 | 9大境界（炼气/筑基/金丹/元婴/化神/合体/大乘/渡劫/飞升），5层世界 |\n| 种族 | 19个可创角种族，3大阵营（天道/洪荒/幽冥）+ 混沌中立 |\n| 游戏时间 | 现实:游戏 = 1:3 |\n\n---\n\n## 2. 埋点事件 Schema 设计\n\n### 2.1 通用字段定义\n\n所有埋点事件（客户端 + 服务端）共享以下通用字段：\n\n| 字段名 | 类型 | 必填 | 说明 |\n|--------|------|------|------|\n| `event_id` | string(uuid) | 是 | 事件唯一标识，用于幂等去重 |\n| `event_name` | string | 是 | 事件名称，格式：`{module}.{action}`，如 `combat.battle_end` |\n| `event_category` | string | 是 | 事件分类：`client` / `server` |\n| `timestamp` | int64 | 是 | 事件发生时间戳（毫秒级，UTC） |\n| `event_date` | string | 是 | 事件日期分区键，格式 `YYYY-MM-DD`（UTC） |\n| `player_id` | string(uuid) | 是 | 玩家账户 ID（对应 `players.id`） |\n| `character_id` | string(uuid) | 否 | 角色 ID（对应 `characters.id`），创角前事件为空 |\n| `device_id` | string | 是 | 设备指纹哈希（对应 `players.device_id_hash`） |\n| `session_id` | string(uuid) | 是 | 会话 ID，一次登录周期内不变 |\n| `client_version` | string | 是 | 客户端版本号，格式 `主.次.热更.资源`（如 `1.2.3.4`） |\n| `server_id` | string | 是 | 服务实例标识（如 `nakama-prod-01`） |\n| `platform` | string | 是 | 平台：`ios` / `android` / `pc` / `web` |\n| `channel` | string | 否 | 渠道包标识（如 `official` / `huawei` / `xiaomi`） |\n| `network_type` | string | 否 | 网络类型：`wifi` / `4g` / `5g` / `offline` |\n| `world_tier` | int | 否 | 当前世界层级（1~5），创角前为空 |\n| `realm_tier` | int | 否 | 当前大境界（1~9），创角前为空 |\n| `race_id` | string | 否 | 当前种族 ID，创角前为空 |\n| `config_version` | string | 否 | 服务端配置版本号（Nacos `server.config.version`） |\n| `ab_group` | string | 否 | A/B 实验分组标识，多个实验用逗号分隔 |\n| `extra` | jsonb | 否 | 扩展字段，存放事件特有数据 |\n\n**命名规范**：\n- `event_name` 采用 `{module}.{action}` 两段式命名\n- module 枚举值：`account` / `character` / `cultivation` / `combat` / `economy` / `social` / `explore` / `event` / `ui` / `system` / `hotupdate` / `push`\n- action 使用 snake_case，动词在前（如 `battle_start`、`realm_breakthrough`、`item_trade`）\n\n### 2.2 客户端埋点事件 Schema\n\n客户端埋点由 Cocos Creator 3.x SDK 在本地采集，通过批量上报服务发送。\n\n#### 2.2.1 UI 曝光事件\n\n```json\n{\n \"event_name\": \"ui.impression\",\n \"extra\": {\n \"page_id\": \"main_hall\",\n \"component_id\": \"event_panel_world_pulse\",\n \"component_type\": \"panel\",\n \"position\": 0,\n \
|
