# 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. 推荐上线顺序

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

## 3. 一次性历史归档建议

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

推荐分阶段：

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

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

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

3. 再逐步提高：

```yaml
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 为止
- 每次任务都会重算 lookback 窗口内的数据，再通过 upsert 覆盖旧值
- 默认只回算近 7 个自然日，这样不会和“30 天前数据归档”窗口重叠
- 即使配置误设得过大，代码也会自动限制为 `retentionDays - 1`，避免边界日期统计失真
- 所以近 7 个自然日如果有补写、重复清理、延迟写入，daily stats 会被自动修正

默认值：

```yaml
adx:
  ad-bid-report-stats-lookback-days: 7
```

这意味着：

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

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

## 5. 建议核对项

开启后建议核对：

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

## 6. 关键配置

```yaml
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-lookback-days: 7
```