数据周报生成器

把指标 CSV 变成结构化周报。算得准，但不替你思考。

核心分工

| 谁 | 负责什么 | |---|---| | 脚本 | 周期聚合、算环比、标异常、查数据缺失、套模板（确定性计算） | | AI / 人 | 解释「为什么涨/跌」、写下周行动项（需要业务理解） |

脚本会在周报末尾刻意留一个「待补充分析」空白段——数据只能说明「发生了什么」，「为什么」和「怎么办」必须人工填写，避免产出看似完整实则空洞的周报。

快速开始

# 生成周报
python3 scripts/weekly_report.py --csv metrics.csv --output report.md

# 自定义周期（默认 7 天）与异常阈值（默认 30%）
python3 scripts/weekly_report.py --csv metrics.csv --period 14 --anomaly 20

# JSON 输出（便于接入其他流程）
python3 scripts/weekly_report.py --csv metrics.csv --json

输入格式

支持两种，自动识别：

宽表（日期 + 多个指标列）

date,uv,orders,gmv
2026-09-01,1000,50,5000
2026-09-02,1200,62,6200

长表（日期 + 指标名 + 值）

date,metric,value
2026-09-01,uv,1000
2026-09-01,orders,50

日期列支持 date / 日期 / day / 时间 / stat_date，格式支持 2026-09-01、2026/09/01、20260901。

聚合方式自动推断

| 指标名特征 | 聚合方式 | 例 | |---|---|---| | 含「粉丝/累计/存量/总量」 | 期末值 | 粉丝数 | | 含「率/占比/均价/客单价」 | 均值 | 转化率、客单价 | | 其他 | 求和 | uv、订单数、gmv |

校验与提示

• 异常波动：环比变动 ≥ 阈值（默认 30%）标记为「需关注」
• 数据质量：本期缺失天数会被统计并提示「环比可能失真」
• 除零保护：上期为 0 时不计算百分比（避免误判为「暴涨」）

实测验证

单元测试 tests/test_weekly_report.py 12 项全部通过，覆盖数值/日期解析、宽表与长表读取、缺失日期列报错、聚合方式推断、环比计算（含除零返回 None）、周期切分、报告结构、异常标记、数据缺失提示。

已知限制

• 需要至少能覆盖「本期 + 上期」的数据量，否则无法计算环比（脚本会明确提示）
• 「同比」需要更长历史数据，当前版本提供环比为主
• 异常阈值是固定百分比，不区分指标波动特性

依赖

仅 Python 标准库。