adx_report 回灌说明

本文档说明如何将 tencent_ad_bid_events、honor_ad_bid_events、kuaishou_ad_bid_events 的老历史数据归档到 adx_report，并生成日汇总表。

1. 当前代码行为

主库热表继续保留最近 30 天数据
后台任务开启后，会把 30 天前数据按月搬到 adx_report
归档时会先按 created_at 选出一批候选 id，再按同一批 id 搬运和删除，避免 LIMIT 边界误删
月历史表命名规则：
- tencent_ad_bid_events_history_YYYYMM
- honor_ad_bid_events_history_YYYYMM
- kuaishou_ad_bid_events_history_YYYYMM
日汇总表：
- tencent_ad_bid_events_daily_stats
- honor_ad_bid_events_daily_stats
- kuaishou_ad_bid_events_daily_stats

2. 推荐上线顺序

先发版，让代码具备 adx_report 建库、归档、日汇总能力
在测试环境确认 adx.ad-bid-report-enabled=true 后运行正常
生产环境先保持 adx.ad-bid-report-enabled=false
确认主库 / 报表库实例容量、慢 SQL、锁冲突可接受后，再开启生产开关

3. 一次性历史归档建议

生产环境如果已经积累了大量超过 30 天的老数据，建议不要一开开关就直接放大批量归档。

推荐分阶段：

先把生产配置中的批次控制调小

adx:
  ad-bid-report-enabled: true
  ad-bid-report-archive-batch-size: 2000
  ad-bid-report-archive-max-batches-per-run: 5

观察 1 到 2 个归档周期，确认：
- 主库写入延迟正常
- adx_report 月表创建正常
- 没有异常锁等待
再逐步提高：

adx:
  ad-bid-report-archive-batch-size: 5000
  ad-bid-report-archive-max-batches-per-run: 20

4. 日汇总补数说明

当前代码会按 adx.ad-bid-report-stats-lookback-days 回算热表近 N 天数据并 upsert 到日汇总表。

当前 daily stats 统计维度为：

stat_date
platform
account_id
tag_id
event_type

当前 daily stats 指标为：

bid_count：该维度下的总事件数
impression_count：曝光数
click_count：点击数
unique_media_trace_count：按 media_trace_id 去重后的事件数
price_sum：price > 0 的记录数

说明：

汇总源数据来自三张热表，不直接扫月历史表
统计窗口不包含当天数据，只统计到昨天 24:00 为止
归档任务每 5 分钟跑一次，但 daily stats 默认每天按上海时区 01:00、10:00、17:00 跑三次
每次 daily stats 执行时，会重算 lookback 窗口内的数据，再通过 upsert 覆盖旧值
默认只回算近 7 个自然日，这样不会和“30 天前数据归档”窗口重叠
即使配置误设得过大，代码也会自动限制为 retentionDays - 1，避免边界日期统计失真
所以近 7 个自然日如果有补写、重复清理、延迟写入，daily stats 会被自动修正

默认值：

adx:
  ad-bid-report-stats-run-times: ["01:00", "10:00", "17:00"]
  ad-bid-report-stats-lookback-days: 7

这意味着：

最近 7 天统计会自动修正
更久远的老历史不会自动全量重刷 daily stats

如果需要补很久以前的 daily stats，建议单独执行离线 SQL 按月回灌。

5. 建议核对项

开启后建议核对：

adx_report 是否自动创建
月历史表是否按 YYYYMM 创建
三张 daily stats 表是否有数据
主库热表 30 天前数据是否开始下降
在线链路是否仍只查热表，没有影响监测和回传

6. 关键配置

adx:
  report-database-name: "adx_report"
  ad-bid-report-enabled: false
  ad-bid-report-interval: 5m
  ad-bid-report-retention-days: 30
  ad-bid-report-archive-batch-size: 5000
  ad-bid-report-archive-max-batches-per-run: 20
  ad-bid-report-stats-run-times: ["01:00", "10:00", "17:00"]
  ad-bid-report-stats-lookback-days: 7

ADX_REPORT_BACKFILL.md 3.8 KB History Raw