ppt/ppt_manager/README.md

# 📊 PPT智能管理系统

PPT管理系统，实现**静态模板内容**与**动态数据内容**的智能合并。

---

## 📚 从零开始完整教程（必读）

### 第一步：创建你的第一个静态PPT模板

#### 方式A: 运行脚本快速生成示例（推荐新手）

```bash
cd f:\ppt\ppt_manager
python create_sample_template.py
```

✅ 自动生成: `static_ppt/macro_analysis_template.pptx` (23页空白模板)

#### 方式B: 手工创建属于你自己的模板（正式项目用）

1. **打开Microsoft PowerPoint → 新建空白演示文稿**

2. **保存到**: `f:\ppt\ppt_manager\static_ppt\你的模板名称.pptx`

3. **页面布局建议**:
   | 页码 | 内容类型 | 说明 |
   |------|----------|------|
   | 1页 | 封面 | static |
   | 2页 | 目录 | static |
   | 3页 | 分析框架 | static |
   | 4页 | GDP图表页 | **dynamic** → Python脚本生成 |
   | 5页 | CPI图表页 | **dynamic** → Python脚本生成 |
   | 6-23页 | 其他原理内容 | static |

4. **保存模板**

---

### 第二步：理解 `config/project_config.yaml` 配置

```yaml
projects:
  macro_analysis:                    # 项目ID
    name: "宏观数据分析报告"          # 显示名称
    static_ppt: "static_ppt/macro_analysis_template.pptx"   # 模板路径 ✅
    total_slides: 23                                   # 总页数
    slide_mapping:
      1: static                      # 第1页 = 静态来自模板
      2: static                      # 第2页 = 静态来自模板
      3: static                      # 第3页 = 静态来自模板
      4: dynamic_chart_gdp           # 第4页 = 动态执行GDP脚本生成图片插入
      5: dynamic_chart_inflation     # 第5页 = 动态执行CPI脚本生成图片插入
      6: static
      ...更多...
      23: static
    
    dynamic_generators:              # 动态key 到 脚本文件路径 的映射
      dynamic_chart_gdp: "scripts/gdp_chart.py"
      dynamic_chart_inflation: "scripts/inflation_chart.py"
      dynamic_table_employment: "scripts/employment_table.py"
      dynamic_chart_trade: "scripts/trade_chart.py"
      dynamic_content_market: "scripts/market_analysis.py"
```

**关键点**:
- `slide_mapping` 里的 key 如果不是 `static`，就去 `dynamic_generators` 里找对应脚本执行
- 脚本返回PNG图片路径，系统把图片插入对应新生成的页面

---

### 第三步：更新动态数据（改脚本取真实数据）

打开 `scripts/gdp_chart.py` 改成你自己的采集逻辑：

```python
def generate(output_dir):
    import pandas as pd
    
    # --------------------------
    # 在这里替换成你真实的取数代码:
    # --------------------------
    # df = pd.read_sql("SELECT * FROM gdp_stats", conn)
    # 或 df = pd.read_csv("你的真实GDP数据文件.csv")
    # 或 API调用: requests.get("https://stats.gov.cn/api/gdp")
    
    # 下面是示例模拟数据，跑通后替换成真实采集代码
    quarters = ['2026Q1', '2026Q2']
    actual_data_from_api = [5.2, 5.1]
    
    # 生成matplotlib图
    import matplotlib.pyplot as plt
    plt.plot(quarters, actual_data_from_api)
    plt.savefig(f"{output_dir}/my_real_gdp_chart.png")
    
    return f"{output_dir}/my_real_gdp_chart.png"
```

**其他脚本同理修改**:
- CPI → `scripts/inflation_chart.py`
- 就业数据 → `scripts/employment_table.py`
- 贸易数据 → `scripts/trade_chart.py`
- 市场分析 → `scripts/market_analysis.py`

---

### 第四步：启动Web生成

```bash
pip install -r requirements.txt
python app.py
```

浏览器打开 **http://localhost:5000**

点击项目卡片上的 🚀 **"开始生成"** 按钮

✅ 生成的PPT在 `f:\ppt\ppt_manager\output\` 目录

---

## ✨ 核心特性

- 📁 **静态PPT管理**: 固定不变的原理内容放在本地PPT模板中
- 🔄 **动态内容生成**: Python脚本负责数据采集、图表生成
- 🎯 **页面映射配置**: YAML配置文件定义每页是静态还是动态
- 🖱️ **一键生成**: Web界面点击按钮自动合成最终PPT
- 📝 **日志记录**: 使用loguru完整记录生成过程

## 📁 项目结构

```
ppt_manager/
├── static_ppt/              # 静态PPT模板目录
│   └── macro_analysis_template.pptx    # 23页模板示例
├── config/
│   └── project_config.yaml  # 项目配置：页面映射关系
├── scripts/                  # 动态内容生成脚本
│   ├── gdp_chart.py         # GDP图表生成
│   ├── inflation_chart.py   # CPI/PPI图表
│   ├── employment_table.py  # 就业数据表
│   ├── trade_chart.py       # 进出口图表
│   └── market_analysis.py   # 市场分析图表
├── dynamic_content/          # 动态生成的图片存放
├── output/                   # 👉 最终生成的PPT在这里
├── logs/                     # 日志目录
├── src/
│   ├── config_loader.py      # 配置加载器
│   ├── ppt_core.py           # PPT核心操作
│   ├── dynamic_generator.py  # 动态内容生成器
│   └── ppt_generator.py      # 主合成引擎
├── templates/
│   └── index.html            # Web界面
├── app.py                     # Flask Web应用（端口5000）
├── main.py                    # 命令行入口
├── create_sample_template.py # ✅ 快速创建示例模板脚本
└── requirements.txt           # Python依赖
```

## 🚀 快速开始（TL;DR）

### 1. 安装依赖

```bash
cd ppt_manager
pip install -r requirements.txt
```

### 2. 初始化示例静态PPT模板

```bash
python create_sample_template.py
```

### 3. 运行系统

**方式一：Web界面（推荐）**
```bash
python app.py
```
然后在浏览器打开: http://localhost:5000

**方式二：命令行**
```bash
python main.py macro_analysis
```

## ⚙️ 配置说明

在 `config/project_config.yaml` 中配置：

```yaml
projects:
  macro_analysis:
    name: "宏观数据分析报告"
    static_ppt: "static_ppt/macro_analysis_template.pptx"
    total_slides: 23
    slide_mapping:
      1: static
      2: static
      3: static
      4: dynamic_chart_gdp
      5: dynamic_chart_inflation
      ...
    dynamic_generators:
      dynamic_chart_gdp: "scripts/gdp_chart.py"
      dynamic_chart_inflation: "scripts/inflation_chart.py"
      ...
```

## 📝 动态脚本编写规范

每个动态脚本必须包含一个 `generate(output_dir)` 函数，返回生成的图片路径：

```python
def generate(output_dir):
    # 1. 采集数据（API/爬虫/数据库等）
    # 2. 生成图表（matplotlib/plotly等）
    # 3. 返回图片完整路径
    return str(image_path)
```

## 🎯 使用场景示例

| 页面 | 类型 | 内容 | 更新频率 |
|------|------|------|----------|
| 1-3页 | static | 封面、目录、分析框架 | 固定不变 |
| 4页 | dynamic | GDP趋势图 | 每月更新 |
| 5页 | dynamic | CPI/PPI通胀图 | 每月更新 |
| 7页 | dynamic | 就业数据表 | 每月更新 |
| 10页 | dynamic | 进出口贸易 | 每月更新 |
| 13页 | dynamic | A股市场分析 | 每周更新 |
| 其他页 | static | 原理、方法论 | 固定不变 |

---

## ❓ 常见问题排查

**Q1: 报错 `FileNotFoundError: 静态PPT文件不存在: static_ppt/macro_analysis_template.pptx`**

运行 `python create_sample_template.py` 生成示例模板

**Q2: 访问localhost:5000首页报错**

检查Flask是否正常启动在5000端口，以及templates目录是否存在

**Q3: 生成的PPT里动态页是空白**

检查动态脚本是否报错，查看logs目录下日志排查