# 月报额外导出表数据入库说明

## 目的

把 2026 年 5 月月报旁路验证过程中额外导出的表数据，按月存入云端 PostgreSQL，形成可追溯的月度快照。这样一年后做同比时，可以直接查历史月度快照，不依赖平台届时是否还能重新导出同一份京东/千牛/推广/月报数据。

## 数据库

```text
Host: wwyl-cloud
Database: liangzhu_qianniu
Schemas: raw, fact
Batch key: monthly_report_2026_05_validation_v1
```

不在文档中记录任何数据库密码、Cookie、HAR、访问令牌或签名下载链接。

## 本次入库来源

脚本读取本项目 `work/` 下的已验证清洗结果：

| 来源文件 | 表段 | 入库行数 | 月份范围 |
|---|---:|---:|---|
| `store_monthly.json` | store | 32 | 2025-04 至 2026-05，含 2026-05 天猫/淘宝/京东 |
| `product_monthly.json` | product | 1746 | 2026-01 至 2026-05 |
| `promo_plan_rows.json` | promotion | 959 | 2026-01 至 2026-05 |
| `flow_source_summary.json` | traffic_source | 72 | 2026-04 至 2026-05 |

## 新增表

### 原始快照

```text
raw.monthly_report_export_row
```

保存每一行原始 payload，字段包括：

- `batch_key`
- `snapshot_month`
- `period_end`
- `section`：`store` / `product` / `promotion` / `traffic_source`
- `source_platform`
- `store_code`
- `store_name`
- `source_file`
- `row_key`
- `row_hash`
- `payload jsonb`

### 规范化事实快照

```text
fact.monthly_store_snapshot
fact.monthly_product_snapshot
fact.monthly_promotion_snapshot
fact.monthly_traffic_source_snapshot
```

这些表从 raw payload 中抽取常用字段，保留 `payload jsonb`，便于未来口径调整时重新解释原始数据。

## 本次执行结果

Dry-run 与真实入库均已执行。真实入库结果：

```text
raw.monthly_report_export_row:                 2809
fact.monthly_store_snapshot:                     32
fact.monthly_product_snapshot:                 1746
fact.monthly_promotion_snapshot:                959
fact.monthly_traffic_source_snapshot:            72
```

2026-05 关键行数：

```text
store:            3
product:        405
promotion:      204
traffic_source:  38
```

2026-05 店铺快照已含京东本次补齐的退款/实际成交口径：

```text
京东  成交金额 7229.10；退款 660.00；实际成交 6569.10；商品件数 70
天猫  实际成交 36113.89
淘宝  实际成交 21005.72
```

## 查询示例

### 查某月三渠道店铺快照

```sql
SELECT source_platform, store_name, visitor_count, payment_amount,
       refund_amount, net_payment_amount, payment_buyer_count,
       payment_item_count, payment_conversion_rate
FROM fact.monthly_store_snapshot
WHERE batch_key = 'monthly_report_2026_05_validation_v1'
  AND snapshot_month = '2026-05-01'
ORDER BY source_platform;
```

### 一年后同比查询

```sql
SELECT cur.source_platform,
       cur.net_payment_amount AS cur_net,
       base.net_payment_amount AS base_net,
       CASE WHEN base.net_payment_amount IS NULL OR base.net_payment_amount = 0
            THEN NULL
            ELSE ROUND((cur.net_payment_amount - base.net_payment_amount)
                       / base.net_payment_amount * 100, 2)
       END AS yoy_pct
FROM fact.monthly_store_snapshot cur
LEFT JOIN fact.monthly_store_snapshot base
  ON base.batch_key = cur.batch_key
 AND base.source_platform = cur.source_platform
 AND base.snapshot_month = cur.snapshot_month - interval '1 year'
WHERE cur.batch_key = 'monthly_report_2026_05_validation_v1'
  AND cur.snapshot_month = '2026-05-01'
ORDER BY cur.source_platform;
```

当前 2026-05 可比同比验证结果：天猫、淘宝已有 2025-05 基准；京东当前仍无 2025-05 基准，所以 2026-05 京东同比为空，但 2026-05 京东快照已经存入，2027-05 可作为同比基准。

## 入库脚本

```text
work/import_monthly_report_snapshots.py
```

常用命令：

```bash
# dry-run：只生成本地 stage，并到远端检查行数，不写库
python3 work/import_monthly_report_snapshots.py --batch-key monthly_report_2026_05_validation_v1

# apply：创建表并写入数据库；同一个 batch_key 可重复执行，会先删除该 batch 的旧记录再重写
python3 work/import_monthly_report_snapshots.py --batch-key monthly_report_2026_05_validation_v1 --apply
```

## 后续接入建议

1. 月报生成器每月完成后，把清洗好的 `store/product/promotion/traffic_source` 快照入库。
2. 每个月使用新 batch_key，例如 `monthly_report_2026_06_validation_v1`。
3. 若同月口径修正，保持同 batch_key 重跑可覆盖该批；若需要保留多个版本，则使用 `_v2` 并在月报生成时明确选择最新已确认 batch。
4. 日报/看板流水仍使用现有 daily fact/mart；月报补充快照只服务月报、同比、历史追溯，避免污染日常自动化口径。