kra-new/docs/sw6-to-kra/report-build-source-notes.md

日汇总和区服汇总任务迁移

核对旧 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 原生任务创建、手动触发、执行日志，核对两种报表实际落库且任务仍为禁用。

当前验证状态统一见 验收与性能记录，不再维护阶段性运行报告。

任务、表与接口的对应关系

这些任务是 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 保持停用，需要时手动运行。周期、时区和超时/重试参数保持原配置，详见 验收记录。

报表输入索引由版本 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，不改写原始业务字段。