65 lines
7.4 KiB
Markdown
65 lines
7.4 KiB
Markdown
# 日汇总和区服汇总任务迁移
|
||
|
||
核对旧 main 的两个 `SwReport*BuildServiceImpl`、两个 SnailJob 执行器、`ReportIdentityHelper` 和 `ReportBuildRangeSupport`。
|
||
|
||
## 原始数据口径
|
||
|
||
- 日汇总注册只取 `tab_user.puid=0`，注册时间按原 `CAST(register_time AS UNSIGNED)` 语义。按平台、渠道、首次游戏分组。
|
||
- 日汇总活跃来自 `tab_user_day_login`，必须能找到同平台主账号。记录无平台时，仅当全库同 ID 恰好一个主账号时才接受；跨平台存在多个主账号时跳过。缺渠道回退账号的渠道。
|
||
- 日汇总充值取当天成功支付，金额不限制主账号；付款用户不存在时模式 0 仍计账号，模式 1 因无身份证不计身份。没有付款用户 ID 的成功单仍计金额。
|
||
- 新增付费先取同一分组内“当日注册账号 ∩ 当日付费账号”，再转身份证；不能直接用身份证交集，否则会把同证件的其他账号误认成新增付费。
|
||
- 区服注册取 `tab_user_play_info.create_time` 的创角，活跃取 `play_time`，不套用日注册/登录的主账号限制。区服编号去首尾空白，保留前导零；创角/活跃缺游戏 ID 时忽略，充值缺游戏 ID 沿用 0。区服汇总没有新增付费指标。
|
||
- 两类报表均按日、平台、渠道、游戏（区服额外编号）生成模式 0/1 两行及对应身份键。模式 1 去首尾空格、仅将末尾 X 转 x，空身份证丢弃。金额两种模式相同，查询层仍固定读取模式 0。
|
||
- 游戏名作为当前游戏资料的快照写入。已知平台的用户按平台分组、ID 排序后分批加载；缺平台的事件仍读取全部同号用户以判断唯一主账号。平台作为字典键的一部分，不混淆跨平台同号。
|
||
|
||
## 原子替换与任务
|
||
|
||
- 所有原始数据读取、计算和两张报表替换在同一事务。按报表类型＋日期的锁表串行同分区重建，避免不同任务同时回跑同一天。读不到必要源表/目标表时拒绝重建，不清空既有数据。
|
||
- 汇总、身份键按批写入，失败或取消回滚原有分区；其他日期不变。输出日期固定 `yyyy-MM-dd`，不采用驱动返回的时间格式作为写入日期。
|
||
- 任务方法保留 `swReportDayTodayTask` / `YesterdayTask` / `BackfillTask` 和对应 `swReportServerDay*` 六个名字。已有迁移 SQL 保留旧执行器名和 `_execution` 参数，可直接绑定 Kra 方法执行器。
|
||
- 回跑参数为 startDate/endDate；每个缺省日期独立取昨日，闭区间逐日重建、日间暂停一秒，最后一天不暂停。支持上下文取消，非法/倒置日期报错。
|
||
- 迁移本身不新建默认商务计划、不启用旧导入计划；实际运行状态由管理员单独配置。原始同步表和四张业务报表表沿用旧库结构，不在系统库中伪造完整业务数据源。
|
||
|
||
## 验证边界
|
||
|
||
领域与存储测试覆盖身份/账号规则、重复构建、自然日筛选和身份明细写失败后的原子回滚。真实 TCP HTTP 使用隔离数据库和 Kra 原生任务创建、手动触发、执行日志，核对两种报表实际落库且任务仍为禁用。
|
||
|
||
当前验证状态统一见 [验收与性能记录](validation.md)，不再维护阶段性运行报告。
|
||
|
||
## 任务、表与接口的对应关系
|
||
|
||
这些任务是 Go 内部注册的方法，与已删除的临时验证脚本无关。它们从当前主库读取已同步的原始数据，再生成统计结果；不负责将 SDK 平台数据同步进主库。当前运行服务主库为 sw9。
|
||
|
||
| 任务方法 | 日期范围 | 写入的统计表 |
|
||
|---|---|---|
|
||
| swReportDayTodayTask | 上海时区今天 | tab_sw_report_day、tab_sw_report_day_key |
|
||
| swReportDayYesterdayTask | 上海时区昨天 | 同上 |
|
||
| swReportDayBackfillTask | startDate 至 endDate，含两端 | 同上 |
|
||
| swReportServerDayTodayTask | 上海时区今天 | tab_sw_report_server_day、tab_sw_report_server_day_key |
|
||
| swReportServerDayYesterdayTask | 上海时区昨天 | 同上 |
|
||
| swReportServerDayBackfillTask | startDate 至 endDate，含两端 | 同上 |
|
||
|
||
商务日报读取 `tab_user`（主账号注册及身份资料）、`tab_user_day_login`（登录）、`tab_spend`（成功充值）、`tab_game`（游戏名）。区服日报读取 `tab_user_play_info`（创角 create_time、活跃 play_time）、`tab_spend`、`tab_user`、`tab_game`。
|
||
|
||
`tab_sw_report_day` 按日期、平台、渠道、游戏、去重模式保存注册数、活跃人数、付费人数、新增付费人数和充值金额。`tab_sw_report_server_day` 在相同维度上增加区服，注册数代表创角玩家数，不包含新增付费人数。
|
||
|
||
两个 `_key` 表保存参与统计的身份键，供跨日期、渠道或游戏聚合时重新 `COUNT(DISTINCT identity_key)`。例如同一玩家连续两天活跃，查询这两天的独立活跃人数应为 1，不能直接将两个日活人数相加。`dedup_mode=0` 使用账号 ID，`dedup_mode=1` 使用规范化身份证；空身份证不计入模式 1。`metric` 为注册 1、活跃 2、付费 3，商务日报另有新增付费 4；金额查询只读模式 0，避免两种模式重复累加。
|
||
|
||
每次重建会在一个事务内锁定“报表类型＋日期”，读取原始数据，删除统计表及对应 key 表该 `stat_date` 的旧行，批量写入新结果。读取或写入失败、取消时回滚；每个日期单独提交，回跑中途失败不会撤销此前已完成日期。除统计表外，会使用 `sys_business_report_build_locks` 保存互斥锁键，任务执行框架将结果记入 `sys_timed_task_logs`。原始用户、充值和登录记录不会被这些任务改写。
|
||
|
||
| 使用方 | 接口 | 依赖 |
|
||
|---|---|---|
|
||
| 渠道数据统计 | GET /sw/channelData/list | 商务日报两表 |
|
||
| 游戏数据 | GET /sw/gameData/list | 商务日报两表 |
|
||
| 三类排行榜 | GET /sw/rank/channel、/business、/game | 商务日报两表 |
|
||
| 仪表盘/工作台 | GET /sw/workbench/summary、/registerTop、/payRank | 商务日报两表；汇总中的新增渠道另查渠道表 |
|
||
| 商务画像 | GET /sw/business/:userId/portrait、/sw/business/bindPlatform/portrait | 商务日报两表 |
|
||
| 渠道画像及游戏分布 | GET /sw/promote/portrait、/sw/promote/game-distribution | 商务日报两表；付费分层还会读取原始充值 |
|
||
| 区服分析 | GET /sw/serverAnalysis/list | 区服日报两表 |
|
||
|
||
普通渠道列表、注册明细、充值明细、渠道激活、工作台未登录榜，以及游戏/区服下拉选项不直接使用这四张汇总表。预警检测 `alertTriggerTask` 另行读取原始注册/充值数据，不由这些汇总任务生成预警。
|
||
|
||
今天任务用于当天持续刷新，昨天任务用于补算昨日完整数据，backfill 用于补历史或纠正迟到数据。2026-11-04 按用户要求与旧计划同步：四条今天/昨天汇总计划和预警计划启用；两个 backfill 保持停用，需要时手动运行。周期、时区和超时/重试参数保持原配置，详见 [验收记录](validation.md)。
|
||
|
||
报表输入索引由版本 `202611040014_business_report_build_indexes` 增量添加：`tab_user.idx_sw_user_report_identity` 覆盖用户身份及渠道字段，`tab_user_play_info.idx_sw_play_report_active` 覆盖活跃时间查询的全部读取字段。迁移跳过未接入的业务表，重复执行不重建已有同列索引，同名异列索引报错。MySQL 使用 `ALGORITHM=INPLACE, LOCK=NONE`，不改写原始业务字段。
|