# 通用数据报告 PPT 生成器

输入任意 Excel/CSV 数据文件，自动生成包含原生可编辑图表的高质量数据报告 PPT。

## 核心特性

- **通用数据兼容**：不依赖固定 Schema，自动探查任意 Excel/CSV 文件的数据结构、字段语义和统计特征
- **原生可编辑图表**：使用 `python-pptx` 生成原生 Chart 对象，非静态图片，生成后可在 PowerPoint 中直接编辑数据和样式
- **智能分析推荐**：自动识别可量化指标，推荐可视化方案、页面结构和洞察文案
- **六项用户确认**：生成前强制确认报告周期、核心指标、受众场景、视觉风格、页面结构、字段映射，避免生成偏离需求的报告
- **质量自检引擎**：四类 25 项质量检查（布局/视觉/内容/数据），自动检测并迭代修复至达标
- **多主题支持**：5 套预设主题（商务经典、清新简约、科技蓝调、暖橙活力、暗夜深邃），支持自定义配色
- **专业分析标准**：内置《专业数据分析师手册》，确保每页分析包含业务判断、数据证据、对比关系和行动建议

## 安装要求

```bash
pip install python-pptx pandas numpy openpyxl
```

## 快速开始

### 1. 使用预设报告类型（日报/周报/月报）

```python
from scripts.ppt_builder import build_daily_report, build_weekly_report, build_monthly_report
from datetime import datetime

# 日报
build_daily_report('data.xlsx', datetime(2026, 4, 10), 'daily_report.pptx')

# 周报
build_weekly_report('data.xlsx', datetime(2026, 4, 10), 'weekly_report.pptx')

# 月报
build_monthly_report('data.xlsx', datetime(2026, 4, 10), 'monthly_report.pptx')
```

### 2. 使用通用构建器（推荐）

```python
from scripts.ppt_builder import build_report, quality_assured_build
from scripts.report_config import ReportConfig, MetricDef, PageDef

# 创建配置
config = ReportConfig(
    title='销售数据月度报告',
    period_type='monthly',
    source_label='销售部',
    theme='business_classic',
    quality_threshold=85,
    max_fix_iterations=5,
)

# 添加指标（根据数据探查结果配置）
config.metrics = [
    MetricDef(name='总需求台数', column='总需求台数', agg='sum', unit='台'),
    MetricDef(name='已下单台数', column='已下单', agg='sum', unit='台'),
    MetricDef(name='转化率', column='转化率', agg='mean', unit='%', fmt='.1f'),
]

# 添加页面
config.pages = [
    PageDef(page_type='kpi_overview', title='月度总览'),
    PageDef(page_type='trend', title='30日追踪趋势'),
    PageDef(page_type='distribution', title='区域分布'),
    PageDef(page_type='ranking', title='TOP10目的国'),
    PageDef(page_type='summary', title='总结与建议'),
]

# 基础构建
build_report('data.xlsx', config, 'output.pptx')

# 带质量自检的构建（推荐）
prs, issues = quality_assured_build('data.xlsx', config, 'output_qa.pptx')
```

### 3. 完整工作流

```python
from scripts.data_loader import load_generic_excel
from scripts.data_profiler import profile_dataframe
from scripts.agent_analyzer import analyze_and_recommend

# 1. 加载数据
df = load_generic_excel('data.xlsx')

# 2. 数据探查
profile = profile_dataframe(df)
print(f"检测到 {profile['num_rows']} 行数据，{profile['num_cols']} 个字段")

# 3. 智能推荐
recs = analyze_and_recommend(profile, period_type='monthly')
print(f"推荐指标: {[m['name'] for m in recs['suggested_metrics']]}")
print(f"推荐页面: {[p['page_type'] for p in recs['suggested_pages']]}")

# 4. 用户确认后构建配置并生成
# ...（见上方配置示例）
```

## 工作流程

```
用户数据 (.xlsx/.csv)
    ↓
数据加载与清洗 (data_loader.py)
    ↓
自动数据探查 (data_profiler.py)
    - Schema 检测、统计特征、数据质量评分
    ↓
智能分析与推荐 (agent_analyzer.py)
    - 指标推荐、页面结构、可视化方案
    ↓
【六项用户确认】
    1. 报告周期与页数范围
    2. 核心指标集
    3. 受众与决策场景
    4. 视觉风格与配色方向
    5. 页面结构与模板方案
    6. 数据范围与字段映射
    ↓
指标计算 (metrics_calculator.py)
    ↓
PPT 构建 (ppt_builder.py)
    - 动态布局、主题配色、原生图表、深度洞察
    ↓
质量自检与修复 (quality_inspector.py)
    - 布局/视觉/内容/数据 四类检查
    - 自动迭代修复至评分 ≥ 阈值
    ↓
输出 .pptx（全部可编辑）
```

## 目录结构

```
generate-data-report-ppt/
├── assets/                           # PPT 模板文件
│   ├── report-master.pptx            # 日报模板
│   ├── weekly-master.pptx            # 周报模板
│   └── monthly-master.pptx           # 月报模板
├── references/                       # 参考规范文档
│   ├── data-schema.md                # 数据格式与字段映射规范
│   ├── report-structures.md          # 日报/周报/月报标准页面结构
│   ├── chart-specs.md                # 图表类型、配色、数据绑定规范
│   ├── visual-style-guide.md         # 布局、字体、配色视觉规范
│   ├── quality-standards.md          # PPT 生成质量强制规范
│   └── professional-data-analyst-playbook.md  # 专业数据分析洞察标准
├── scripts/                          # 核心代码
│   ├── data_loader.py                # 数据加载与智能清洗
│   ├── data_profiler.py              # 通用数据探查引擎
│   ├── report_config.py              # 报告配置数据模型
│   ├── theme_manager.py              # 多主题配色与模板管理
│   ├── agent_analyzer.py             # 智能分析与推荐
│   ├── metrics_calculator.py         # KPI 计算引擎
│   ├── chart_factory.py              # 原生可编辑图表创建
│   ├── page_layouts.py               # 动态页面布局引擎
│   ├── deep_insights.py              # 结构化深度洞察生成
│   ├── ppt_builder.py                # PPT 组装编排器
│   ├── quality_rules.py              # 质量检查规则定义
│   └── quality_inspector.py          # 质量自检与自动修复引擎
├── SKILL.md                          # 技能定义与 V2 生成契约
└── README.md                         # 本文件
```

## 报告类型

| 类型 | 页数 | 标准结构 | 分析维度 |
|------|------|---------|---------|
| **日报** | 8 页 | 封面 → 核心指标 → 近10天趋势 → 状态分布 → 负责人分布 → TOP8国家 → 异常告警 → 今日要点 | 与昨日对比、与上周同日对比 |
| **周报** | 9 页 | 封面 → 周汇总 → 7日趋势 → 环比分析 → 区域分布 → 国家排行 → 团队追踪 → 问题与建议 → 下周计划 | 周环比(WoW)、周同比(YoY)、7日移动平均 |
| **月报** | 11 页 | 封面 → 目录 → 月度总览 → 订单漏斗 → 区域分布 → TOP10国家 → 30日趋势 → 团队绩效 → 支持需求 → 下月规划 → 尾页 | 环比(MoM)、同比(YoY)、日均值、结构占比 |

> 通用构建器支持自定义页面结构和指标，不限于上述三种预设类型。

## 核心模块说明

### 数据探查（data_profiler.py）

自动分析任意数据结构：
- **Schema 检测**：列名、类型推断、缺失率、唯一值统计
- **统计特征**：数值列的 min/max/mean/std/分位数/偏度/峰度，分类列的分布与 HHI 集中度
- **语义推断**：自动识别时间列、分类列、数值列、ID 列（支持中英文列名关键词匹配）
- **数据质量评分**：完整性、数值健康度、唯一性、时间一致性、分类完整性五维度加权评分
- **衍生关系检测**：自动发现数值列间的加减关系（如 `总需求 - 已下单 = 未下单`）

### 质量自检（quality_inspector.py + quality_rules.py）

| 类别 | 检查项示例 | 严重等级 |
|------|-----------|---------|
| **布局** | 元素飞出边界、图文重叠、占位符未替换、元素紧贴边缘 | Critical/Major |
| **视觉** | 字体不一致、字号异常、颜色对比度不足、图片拉伸 | Major/Minor |
| **内容** | 页面留白过多、KPI 数值为空、图表无数据、分析文本过短 | Critical/Major |
| **数据** | 图表与文本矛盾、页码错乱、数据来源缺失、刻度异常 | Major/Minor |

**评分规则**：严重问题 -20 分/页，主要问题 -10 分/页，次要问题 -3 分/页。默认阈值 85 分，最大迭代修复 5 次。

### 主题管理（theme_manager.py）

内置 5 套主题，每套包含主色、辅色、强调色、背景色、文字色和系列色盘：

- `business_classic` — 商务经典（默认）
- `fresh_minimal` — 清新简约
- `tech_blue` — 科技蓝调
- `warm_orange` — 暖橙活力
- `dark_night` — 暗夜深邃

支持通过 `theme_to_rgb_colors()` 一键转换为 `pptx` 可用的 `RGBColor` 对象。

## 分析质量标准

生成分析文本时严格遵循 `references/professional-data-analyst-playbook.md`：

- 每页分析必须回答五个问题中的至少三个：发生了什么？变化多大？为什么？风险/机会是什么？下一步做什么？
- 每个洞察块必须包含：结论、证据、解释、影响、动作
- 禁止空洞表述（如"表现较好"、"需持续关注"），必须引用具体数字和可执行动作
- 从第 4 页起禁止只做数据总结，必须写出结构、趋势、集中度、转化、缺口、异常和风险

## 配置参考

### ReportConfig 主要字段

| 字段 | 类型 | 说明 |
|------|------|------|
| `title` | str | 报告标题 |
| `period_type` | PeriodType | DAILY / WEEKLY / MONTHLY / CUSTOM |
| `source_label` | str | 数据来源/部门 |
| `theme` | str | 主题名称 |
| `quality_threshold` | int | 质量评分阈值（默认 85） |
| `max_fix_iterations` | int | 最大修复迭代次数（默认 5） |
| `metrics` | List[MetricDef] | 指标定义列表 |
| `pages` | List[PageDef] | 页面定义列表 |

### 支持的页面类型

| page_type | 说明 | 布局 |
|-----------|------|------|
| `cover` | 封面页 | 固定封面布局 |
| `toc` | 目录页 | 章节目录网格 |
| `kpi_overview` | 核心指标概览 | KPI 卡片网格 |
| `trend` | 趋势分析 | 左侧图表 + 右侧洞察 |
| `distribution` | 分布分析 | 左侧图表 + 右侧洞察 |
| `ranking` | 排行分析 | 左侧条形图 + 右侧说明 |
| `summary` | 总结与建议 | 全宽洞察文本 |
| `end` | 结束页 | 固定尾页布局 |

## 注意事项

1. **用户确认是强制步骤**：通用构建器默认 `require_six_confirmations=True`，缺失确认或字段映射无效时必须停止生成
2. **数据探查服务业务意图**：当用户已确认核心指标时，探查结果应映射到实际 Excel 列，不得擅自改变业务焦点
3. **模板是风格资产而非刚性契约**：若模板占位符无法填充，应移除该占位符组件；若 KPI 网格占满空间，应改用其他布局或在后续分析页补充洞察
4. **分析质量优先于布局质量**：即使布局检查通过，仅重述总数/排名/类别名称而无对比、诊断、启示或行动的页面仍不可接受

## License

MIT