315 lines
13 KiB
Markdown
315 lines
13 KiB
Markdown
# Admin 数据大屏游戏数据表技术方案
|
||
|
||
## 目标
|
||
|
||
在新 admin 的 `统计管理 / 数据大屏` 中增加独立的“游戏数据”表，用于按日期、国家、游戏维度查看消耗和收益数据。
|
||
|
||
页面查询不能直接扫描 `likei_wallet.wallet_gold_asset_record_1..12`、第三方回调日志或游戏明细表。所有 admin 查询默认读取游戏维度预聚合表；只有后台刷新任务和手动回填任务允许按时间窗口扫描原始数据。
|
||
|
||
## 现状
|
||
|
||
当前国家数据大屏入口：
|
||
|
||
- 前端路由：`chatapp3-admin/apps/src/router/routes/modules/statistics.ts`
|
||
- 前端页面：`chatapp3-admin/apps/src/views/statistics/datav.vue`
|
||
- 前端接口：`chatapp3-admin/apps/src/api/legacy/datav.ts`
|
||
- 后端 Controller：`DatavRestController`
|
||
- 后端 Service：`CountryDashboardServiceImpl`
|
||
- 后端 Mapper：`CountryDashboardDAO.xml`
|
||
- 现有查询文档：`chatapp3-java/rc-service/rc-service-console/docs/country-dashboard-data-query.md`
|
||
|
||
现有大屏已经聚合了国家维度的 `game_total_flow`、`game_payout`、`game_user`，但没有保留游戏维度。新增功能不改动现有总览口径，新增一套游戏维度查询和预聚合表。
|
||
|
||
## 页面设计
|
||
|
||
在 `datav.vue` 的表格区域增加第三个 tab：
|
||
|
||
- `指标总览`
|
||
- `充值相关数据`
|
||
- `游戏数据`
|
||
|
||
“游戏数据”表复用页面已有筛选项：
|
||
|
||
- 系统：`sysOrigin`
|
||
- 统计时区：`statTimezone`
|
||
- 周期：`periodType`
|
||
- 日期范围：`startDate/endDate`
|
||
- 国家多选：`countryCodes`
|
||
|
||
新增游戏筛选项：
|
||
|
||
- `gameProvider`：游戏厂商，支持 `INTERNAL`、`BAISHUN`、`GAME_OPEN`、`LINGXIAN`，可为空。
|
||
- `gameKeyword`：游戏 ID 或游戏名称模糊搜索。
|
||
|
||
表格字段：
|
||
|
||
| 字段 | 说明 |
|
||
| --- | --- |
|
||
| 日期/周期 | `periodKey`，DAY 显示日期，WEEK/MONTH/ALL 显示周期 |
|
||
| 国家 | `countryCode / countryName` |
|
||
| 游戏厂商 | `gameProvider` |
|
||
| 游戏 ID | `gameId` |
|
||
| 游戏名称 | `gameName` |
|
||
| 消耗 | 用户玩游戏支出，现有钱包口径为 `type = 1` |
|
||
| 返奖 | 游戏返还给用户，现有钱包口径为 `type = 0` |
|
||
| 收益 | `consumeAmount - payoutAmount` |
|
||
| 返奖率 | `payoutAmount / consumeAmount` |
|
||
| 收益率 | `profitAmount / consumeAmount` |
|
||
| 游戏用户数 | 周期内去重用户数 |
|
||
| 流水笔数 | 周期内消耗和返奖记录数 |
|
||
| 更新时间 | 预聚合刷新时间 |
|
||
|
||
表格必须服务端分页，默认 `limit=50`，最大 `limit=200`。
|
||
|
||
## 后端接口
|
||
|
||
新增接口：
|
||
|
||
```http
|
||
GET /console/datav/country-dashboard/game-metrics
|
||
```
|
||
|
||
请求参数：
|
||
|
||
| 参数 | 必填 | 说明 |
|
||
| --- | --- | --- |
|
||
| `sysOrigin` | 是 | 系统来源 |
|
||
| `periodType` | 是 | `DAY` / `WEEK` / `MONTH` / `ALL` |
|
||
| `startDate` | DAY/WEEK/MONTH 必填 | 查询开始日期 |
|
||
| `endDate` | DAY/WEEK/MONTH 必填 | 查询结束日期 |
|
||
| `statTimezone` | 否 | 默认 `Asia/Riyadh` |
|
||
| `countryCodes` | 否 | 多国家码，逗号分隔 |
|
||
| `countryKeyword` | 否 | 国家码或国家名搜索 |
|
||
| `gameProvider` | 否 | 游戏厂商 |
|
||
| `gameKeyword` | 否 | 游戏 ID 或名称搜索 |
|
||
| `cursor` | 否 | 页码，默认 1 |
|
||
| `limit` | 否 | 页大小，默认 50，最大 200 |
|
||
| `sortField` | 否 | 允许 `consumeAmount/payoutAmount/profitAmount/userCount/orderCount` |
|
||
| `sortOrder` | 否 | `ascend/descend` |
|
||
|
||
响应结构：
|
||
|
||
```json
|
||
{
|
||
"current": 1,
|
||
"size": 50,
|
||
"total": 120,
|
||
"records": [
|
||
{
|
||
"periodKey": "2026-05-12",
|
||
"periodName": "2026-05-12",
|
||
"statTimezone": "Asia/Riyadh",
|
||
"countryCode": "SA",
|
||
"countryName": "Saudi Arabia",
|
||
"gameProvider": "BAISHUN",
|
||
"gameId": "1067",
|
||
"gameName": "example game",
|
||
"consumeAmount": "1000.00",
|
||
"payoutAmount": "720.00",
|
||
"profitAmount": "280.00",
|
||
"payoutRate": "72.00%",
|
||
"profitRate": "28.00%",
|
||
"userCount": 86,
|
||
"orderCount": 320,
|
||
"refreshedAt": "2026-05-12 10:20:00"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
后端新增对象建议：
|
||
|
||
- `CountryDashboardGameMetricQryCmd`
|
||
- `CountryDashboardGameMetricCO`
|
||
- `CountryDashboardGameMetricDTO`
|
||
- `CountryDashboardGameMetricService`
|
||
- `CountryDashboardGameMetricDAO`
|
||
- `CountryDashboardGameMetricDAO.xml`
|
||
|
||
## 预聚合表
|
||
|
||
### `country_dashboard_game_period_metric`
|
||
|
||
页面直接查询这张表。
|
||
|
||
```sql
|
||
CREATE TABLE IF NOT EXISTS `country_dashboard_game_period_metric` (
|
||
`id` bigint NOT NULL AUTO_INCREMENT COMMENT '主键',
|
||
`period_type` varchar(16) NOT NULL COMMENT '周期类型:DAY/WEEK/MONTH/ALL',
|
||
`period_key` varchar(32) NOT NULL COMMENT '周期键',
|
||
`stat_timezone` varchar(64) NOT NULL DEFAULT 'Asia/Riyadh' COMMENT '统计时区',
|
||
`period_name` varchar(64) NOT NULL DEFAULT '' COMMENT '周期名称',
|
||
`period_start_date` date DEFAULT NULL COMMENT '周期开始日期',
|
||
`period_end_date` date DEFAULT NULL COMMENT '周期结束日期,开区间',
|
||
`sys_origin` varchar(32) NOT NULL DEFAULT '' COMMENT '系统来源',
|
||
`country_code` varchar(64) NOT NULL DEFAULT 'UNKNOWN' COMMENT '国家码',
|
||
`country_name` varchar(128) NOT NULL DEFAULT 'UNKNOWN' COMMENT '国家名称',
|
||
`game_provider` varchar(32) NOT NULL DEFAULT 'UNKNOWN' COMMENT '游戏厂商',
|
||
`game_id` varchar(64) NOT NULL DEFAULT 'UNKNOWN' COMMENT '游戏ID',
|
||
`game_name` varchar(128) NOT NULL DEFAULT 'UNKNOWN' COMMENT '游戏名称',
|
||
`consume_amount` decimal(20,2) NOT NULL DEFAULT 0.00 COMMENT '用户消耗',
|
||
`payout_amount` decimal(20,2) NOT NULL DEFAULT 0.00 COMMENT '用户返奖',
|
||
`profit_amount` decimal(20,2) NOT NULL DEFAULT 0.00 COMMENT '平台收益',
|
||
`user_count` bigint NOT NULL DEFAULT 0 COMMENT '去重游戏用户数',
|
||
`order_count` bigint NOT NULL DEFAULT 0 COMMENT '流水笔数',
|
||
`refreshed_at` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '最近刷新时间',
|
||
`create_time` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
|
||
`update_time` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
|
||
PRIMARY KEY (`id`),
|
||
UNIQUE KEY `uk_game_period` (`period_type`, `period_key`, `stat_timezone`, `sys_origin`, `country_code`, `game_provider`, `game_id`),
|
||
KEY `idx_game_period_query` (`sys_origin`, `stat_timezone`, `period_type`, `period_key`, `country_code`),
|
||
KEY `idx_game_lookup` (`sys_origin`, `stat_timezone`, `game_provider`, `game_id`, `period_type`, `period_key`),
|
||
KEY `idx_game_period_sort` (`sys_origin`, `stat_timezone`, `period_type`, `period_key`, `consume_amount`)
|
||
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='国家数据大屏游戏维度周期预聚合';
|
||
```
|
||
|
||
### `country_dashboard_game_period_user_metric`
|
||
|
||
用于 `WEEK/MONTH/ALL` 去重用户数，避免直接把日用户数相加导致重复。
|
||
|
||
```sql
|
||
CREATE TABLE IF NOT EXISTS `country_dashboard_game_period_user_metric` (
|
||
`id` bigint NOT NULL AUTO_INCREMENT COMMENT '主键',
|
||
`period_type` varchar(16) NOT NULL COMMENT '周期类型:DAY/WEEK/MONTH/ALL',
|
||
`period_key` varchar(32) NOT NULL COMMENT '周期键',
|
||
`stat_timezone` varchar(64) NOT NULL DEFAULT 'Asia/Riyadh' COMMENT '统计时区',
|
||
`period_name` varchar(64) NOT NULL DEFAULT '' COMMENT '周期名称',
|
||
`period_start_date` date DEFAULT NULL COMMENT '周期开始日期',
|
||
`period_end_date` date DEFAULT NULL COMMENT '周期结束日期,开区间',
|
||
`sys_origin` varchar(32) NOT NULL DEFAULT '' COMMENT '系统来源',
|
||
`country_code` varchar(64) NOT NULL DEFAULT 'UNKNOWN' COMMENT '国家码',
|
||
`country_name` varchar(128) NOT NULL DEFAULT 'UNKNOWN' COMMENT '国家名称',
|
||
`game_provider` varchar(32) NOT NULL DEFAULT 'UNKNOWN' COMMENT '游戏厂商',
|
||
`game_id` varchar(64) NOT NULL DEFAULT 'UNKNOWN' COMMENT '游戏ID',
|
||
`user_id` bigint NOT NULL COMMENT '用户ID',
|
||
`create_time` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
|
||
PRIMARY KEY (`id`),
|
||
UNIQUE KEY `uk_game_period_user` (`period_type`, `period_key`, `stat_timezone`, `sys_origin`, `country_code`, `game_provider`, `game_id`, `user_id`),
|
||
KEY `idx_game_user_count` (`period_type`, `period_key`, `stat_timezone`, `sys_origin`, `game_provider`, `game_id`, `country_code`),
|
||
KEY `idx_game_user_lookup` (`sys_origin`, `stat_timezone`, `user_id`, `game_provider`, `game_id`)
|
||
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='国家数据大屏游戏维度周期用户去重明细';
|
||
```
|
||
|
||
## 数据来源和游戏识别
|
||
|
||
以钱包流水作为财务主口径：
|
||
|
||
- `wallet_gold_asset_record_1..12.type = 1`：消耗
|
||
- `wallet_gold_asset_record_1..12.type = 0`：返奖
|
||
- 金额沿用现有大屏口径：`penny_amount / 100.00`
|
||
- `LUCKY_GIFT`、`LUCKY_GIFT_GOLD_REWARD` 继续归属幸运礼物模块，不并入游戏数据表。
|
||
|
||
游戏维度来源：
|
||
|
||
| 来源 | 识别方式 | 名称补全 |
|
||
| --- | --- | --- |
|
||
| 百顺 | 钱包 `event_id = baishun_order_idempotency.wallet_event_id`，取 `vendor_game_id`；兜底解析 `event_type = BAISHUN_GAME_{gameId}` | `baishun_game_catalog.name` |
|
||
| 统一三方游戏 | 钱包 `event_id = CONCAT('GAME_OPEN:', game_open_callback_log.order_id)`，取 `game_open_callback_log.game_id`；兜底解析 `event_type = GAME_OPEN_{gameId}` | `lingxian_game_catalog.name` 或 `sys_game_list_config.name` |
|
||
| Lucky Box | `game_lucky_box_count` 固定为 `gameProvider=INTERNAL, gameId=LUCKY_BOX` | 固定名称 `Lucky Box` |
|
||
| 其他站内游戏 | 按 `event_type` 映射稳定 `gameId`，例如 `FRUIT_GAME/GAME_FRUIT_* -> FRUIT_GAME`、`LUDO_* -> LUDO_GAME` | 代码内映射或后续配置表 |
|
||
|
||
如果某条流水无法识别具体游戏，落到：
|
||
|
||
- `gameProvider = UNKNOWN`
|
||
- `gameId = event_type`
|
||
- `gameName = event_type`
|
||
|
||
这样可以保证金额不丢失，同时便于后续补映射。
|
||
|
||
## 刷新和回填
|
||
|
||
新增刷新服务建议为 `CountryDashboardGameMetricService`。
|
||
|
||
默认任务：
|
||
|
||
- 每 10 分钟刷新最近 1 天。
|
||
- 每天 00:30 刷新最近 8 天。
|
||
- 支持手动回填，单次最大 366 天，和现有国家大屏保持一致。
|
||
|
||
刷新逻辑：
|
||
|
||
1. 按 `sysOrigin` 和 `statTimezone` 计算周期窗口，转成存储时区时间窗口。
|
||
2. 扫描窗口内原始游戏流水，按 `period + country + gameProvider + gameId` 聚合金额和流水笔数。
|
||
3. 删除对应周期的 `country_dashboard_game_period_user_metric`，写入去重用户明细。
|
||
4. 从用户明细聚合 `user_count`。
|
||
5. 删除并写入对应周期的 `country_dashboard_game_period_metric`。
|
||
6. `ALL` 周期的金额从 `DAY` 周期表汇总，用户数从日级用户明细去重汇总。
|
||
|
||
刷新任务失败只影响游戏数据表，不影响现有国家大屏总览。
|
||
|
||
## 查询性能要求
|
||
|
||
页面查询只能访问 `country_dashboard_game_period_metric`，禁止在请求链路访问以下原始表：
|
||
|
||
- `likei_wallet.wallet_gold_asset_record_1..12`
|
||
- `game_open_callback_log`
|
||
- `baishun_order_idempotency`
|
||
- `game_lucky_box_count`
|
||
- 第三方游戏 catalog 表
|
||
|
||
分页查询必须满足：
|
||
|
||
- `sysOrigin` 必传。
|
||
- `periodType`、`statTimezone` 必须落到联合索引前缀。
|
||
- `DAY/WEEK/MONTH` 查询必须带日期范围，并转成 `period_key` 或 `period_start_date` 范围。
|
||
- `ALL` 只查 `period_type='ALL' AND period_key='ALL'`，不回退全历史实时扫描。
|
||
- `countryKeyword` 和 `gameKeyword` 只允许在已经命中周期范围之后过滤；大范围模糊搜索需要限制日期范围。
|
||
- 只允许白名单排序字段，避免动态 SQL 注入和无法使用索引的任意排序。
|
||
- `limit` 上限 200。
|
||
|
||
刷新任务扫描原始钱包分表时必须带：
|
||
|
||
- `sys_origin`
|
||
- `create_time` 毫秒闭开区间
|
||
- 游戏 `event_type` 白名单或前缀条件
|
||
|
||
现有 wallet 分表有 `idx_sorigin_etype_ctime(sys_origin,event_type,create_time)` 和 `idx_event(event_id)`，刷新 SQL 应优先利用这两个索引。不能对 `create_time` 列包函数做过滤，只能在 SELECT 或 GROUP BY 阶段转换时间。
|
||
|
||
## 实施步骤
|
||
|
||
1. 新增 SQL 迁移：创建 `country_dashboard_game_period_metric` 和 `country_dashboard_game_period_user_metric`。
|
||
2. 新增后端 DTO/Cmd/CO/DAO/Service，并在 `DatavRestController` 暴露 `/country-dashboard/game-metrics`。
|
||
3. 新增刷新任务和手动回填入口，复用现有 `red-circle.country-dashboard.refresh-sys-origins`、`refresh-timezones` 配置。
|
||
4. 新 admin 新增接口方法 `countryDashboardGameMetrics`。
|
||
5. `datav.vue` 增加“游戏数据”tab、游戏筛选项和分页表格。
|
||
6. 首次上线后先回填最近 8 天，再回填历史需要展示的范围。
|
||
|
||
## 验证方案
|
||
|
||
SQL 验证：
|
||
|
||
```sql
|
||
EXPLAIN
|
||
SELECT *
|
||
FROM country_dashboard_game_period_metric
|
||
WHERE sys_origin = 'LIKEI'
|
||
AND stat_timezone = 'Asia/Riyadh'
|
||
AND period_type = 'DAY'
|
||
AND period_key BETWEEN '2026-05-01' AND '2026-05-12'
|
||
ORDER BY consume_amount DESC
|
||
LIMIT 50;
|
||
```
|
||
|
||
预期使用 `idx_game_period_query` 或 `idx_game_period_sort`，不能全表扫描。
|
||
|
||
数据口径验证：
|
||
|
||
```sql
|
||
SELECT SUM(consume_amount), SUM(payout_amount)
|
||
FROM country_dashboard_game_period_metric
|
||
WHERE sys_origin = 'LIKEI'
|
||
AND stat_timezone = 'Asia/Riyadh'
|
||
AND period_type = 'DAY'
|
||
AND period_key = '2026-05-12';
|
||
```
|
||
|
||
对比现有 `country_dashboard_period_metric` 同日同国家汇总的 `game_total_flow/game_payout`，差异应只来自“无法识别但仍落 UNKNOWN”的映射归类，不应出现金额丢失。
|
||
|
||
功能验证：
|
||
|
||
- 查询 DAY 日期范围，表格按日期、国家、游戏拆分。
|
||
- 查询 WEEK/MONTH，用户数为周期内去重，不是日用户数累加。
|
||
- 查询 ALL，不触发实时原始流水扫描。
|
||
- 国家筛选、游戏厂商筛选、游戏关键字筛选、分页、排序都能返回稳定结果。
|
||
- 刷新任务失败时，现有数据大屏总览接口不受影响。
|