|
|
@@ -1,238 +0,0 @@
|
|
|
-# 通用数据报告 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_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. 完整工作流
|
|
|
-
|
|
|
-```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 # 动态页面布局引擎
|
|
|
-│ ├── 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
|
