data-report/generate-data-report-ppt

通用数据报告 PPT 生成器

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

核心特性

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

安装要求

pip install python-pptx pandas numpy openpyxl

快速开始

1. 通用报告构建

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

config = ReportConfig(
    title='销售数据月度报告',
    period_type=PeriodType.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. 完整工作流

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               # 动态页面布局引擎
│   ├── ppt_builder.py                # PPT 组装编排器
│   ├── quality_rules.py              # 质量检查规则定义
│   └── quality_inspector.py          # 质量自检与自动修复引擎
├── SKILL.md                          # 技能定义与 V2 生成契约
└── README.md                         # 本文件

报告类型

类型	页数	标准结构	分析维度
日报	配置驱动	封面 → KPI总览 → 趋势图 → 分布/排行 → 异常告警 → 总结	与昨日对比、周同比
周报	配置驱动	封面 → 周汇总 → 7日趋势 → 环比分析 → 分布/排行 → 总结	周环比(WoW)、移动平均
月报	配置驱动	封面 → 目录 → 月度总览 → 趋势/分布 → 排行/绩效 → 预测规划 → 尾页	环比(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