ppt/ppt_manager_v2/README.md

# 📊 PPT智能管理系统 V2.0 说明书

基于 **锚点定位** + **原生图表更新** + **插件化架构** + **WebSocket实时日志** 的下一代PPT自动化平台。

---

## 🚀 快速开始

### 1. 环境准备

```bash
cd f:\ppt\ppt_manager_v2
pip install -r requirements_v2.txt
```

### 2. 启动WebSocket服务

```bash
python web_socket_app.py
```

### 3. 浏览器访问

打开 **http://localhost:5001**

---

## 📁 项目目录结构

```
ppt_manager_v2/
├── 📄 web_socket_app.py          # WebSocket服务端
├── 📄 orchestrator.py             # 主编排引擎（Pipeline）
├── 📄 requirements_v2.txt         # Python依赖包
├── 📄 README.md                   # 本文件
├──
├── 📂 core/                       # 核心层
│   ├── anchor_engine.py           # ✅ 锚点定位引擎
│   ├── native_chart.py            # ✅ 原生图表数据源更新
│   └── conditional_renderer.py    # ✅ 条件渲染引擎（动态增删页）
├──
├── 📂 plugins/                    # 插件化架构
│   ├── base_generator.py          # BaseGenerator 标准接口
│   └── generators/                # 插件目录（自动扫描注册）
│       ├── gdp_generator.py       # GDP趋势图生成插件
│       └── cpi_generator.py       # CPI/PPI图表生成插件
├──
├── 📂 ai/                         # AI智能化
│   └── llm_analyst.py             # LLM分析师 + Diff对比器
├──
├── 📂 connectors/                 # 多数据源适配
│   └── sql_connector.py           # MySQL/ClickHouse/REST API/CSV
├──
├── 📂 config/
│   └── project_config_v2.yaml     # V2版配置文件范式
├──
├── 📂 templates/                   # Flask模板目录
│   └── index_v2.html              # WebSocket前端页面
├──
├── 📂 logs/                        # 日志目录
└── 📂 web/                         # 备用（template_dir配置用）
    └── templates/
        └── index_v2.html
```

> **输出目录**: `f:\ppt\output\` （所有生成的PPT文件在这里）

---

## 🎯 五大核心增强能力

### 一、PPT核心操作层（从"拼图"到"原生替换"）

#### 1.1 锚点(Anchor)定位引擎 → 无惧页码变动

**痛点解决**: 旧版YAML写 `page: 5`，老板在第3页插一页，所有配置页码全乱。

**新版方案**:

1. 打开你的PPT模板 → 选中一个 **Shape/图表/文本框**
2. 在PowerPoint的 **"选择窗格"** 里给Shape改名（例如：`chart_gdp_trend`）
3. 在YAML里直接配置 **锚点名**，不是页码：

```yaml
anchors:
  - name: chart_gdp_trend       # Shape Name（选择窗格里的名称）
    type: native_chart_update
    plugin: gdp_chart
```

**代码参考**: [core/anchor_engine.py](file:///f:/ppt/ppt_manager_v2/core/anchor_engine.py#L21-L60)

---

#### 1.2 原生图表数据源直接更新（不是插PNG！）

**痛点解决**: 旧版先生成PNG再插入PPT → 图片无法编辑、丢失主题配色和动画效果、文件体积大。

**新版方案**: 用 `python-pptx` 直接替换PPT内嵌图表的Excel数据源：

```python
# 在native_chart.py里的实现
chart_data = CategoryChartData()
chart_data.categories = ['2026Q1', '2026Q2', '2026Q3']
chart_data.add_series('GDP同比增长', [5.2, 5.0, 5.1])
chart.replace_data(chart_data)  # ✅ 原生数据源替换！
```

**这样做的好处**:
- ✅ 生成的PPT里**双击图表可以进入Excel编辑**
- ✅ 自动继承PPT母版的**主题配色**
- ✅ 保留图表原有的**进入/强调动画**效果
- ✅ 文本清晰，不是模糊的点阵图

**代码参考**: [core/native_chart.py](file:///f:/ppt/ppt_manager_v2/core/native_chart.py#L12-L90)

---

#### 1.3 条件渲染与动态增删页

**能力描述**: 支持规则判断动态插入/隐藏页面：

```yaml
slide_conditions:
  - condition: unemployment_rate > 5.1
    action: insert_slide
    template: "risk_warning_template.pptx"
    position: 5
```

表达式求值：`unemployment_rate > 5.1 AND gdp_growth < 5.0` 等复合条件。

**代码参考**: [core/conditional_renderer.py](file:///f:/ppt/ppt_manager_v2/core/conditional_renderer.py#L1-L100)

---

### 二、插件化数据流架构（真正的即插即用）

#### 2.1 BaseGenerator 标准接口

所有插件继承 `BaseGenerator` 抽象基类，实现两个方法：

```python
# plugins/base_generator.py 定义
class BaseGenerator(ABC):
    generator_id = "gdp_chart"
    generator_name = "GDP趋势生成器"
    
    @abstractmethod
    def fetch_data(self, params):    # 步骤A：取数
        pass
    
    @abstractmethod
    def render(self):                 # 步骤B：渲染返回原生图表数据
        pass
```

插件例子 → [plugins/generators/gdp_generator.py](file:///f:/ppt/ppt_manager_v2/plugins/generators/gdp_generator.py)

---

#### 2.2 插件自动扫描注册

启动时系统自动扫描 `plugins/generators/` 目录下所有 `.py` 文件，发现继承 BaseGenerator 且有 `generator_id` 的类自动注册到插件管理器，**无需修改任何注册代码**，真正即插即用。

```
# 启动日志里可以看到：
SUCCESS  | 加载插件 [cpi_chart]: CPI/PPI通胀图表生成器
SUCCESS  | 加载插件 [gdp_chart]: GDP趋势图表生成器
INFO     | 插件扫描完成，共加载 2 个生成器
```

**代码参考**: [plugins/base_generator.py - GeneratorPluginManager.discover_plugins()](file:///f:/ppt/ppt_manager_v2/plugins/base_generator.py#L46-L89)

---

#### 2.3 参数化生成

Web端不是单一"开始生成"按钮，而是传参给后端插件：

```javascript
// 前端传params给WebSocket
socket.emit('start_generation', {
    params: {
        year: 2026,
        quarter: "Q2",
        theme: "保守型"
    }
});
```

插件的 `fetch_data(params)` 拿到这些参数去数据库/API拉对应区间的数据。

---

### 三、WebSocket Web交互体验（实时日志推流）

#### 3.1 启动服务

```bash
python web_socket_app.py
```

控制台输出：
```
=================================================================
 🚀 PPT智能管理系统 V2.0 - WebSocket实时日志版
    请在浏览器打开: http://localhost:5001
=================================================================
```

#### 3.2 前端页面三大区域

| 区域 | 功能 |
|------|------|
| **左上角参数表单** | Year/Quarter 参数化输入 |
| **左下角实时面板** | 动态进度条 0-100% + Loguru日志逐行推送 |
| **右侧边栏** | 已加载插件清单 + 历史生成文件下载列表 |

**WebSocket后端代码**: [web_socket_app.py](file:///f:/ppt/ppt_manager_v2/web_socket_app.py#L1-L95)

---

### 四、主编排引擎 Pipeline

Orchestrator 是串联所有模块的大脑：

```python
# orchestrator.py - run_full_pipeline()
def run_full_pipeline(self):
    self.load_template()          # 1. 打开PPT，扫描所有锚点
    self.run_plugins(params)      # 2. 并行执行所有插件 fetch_data + render
    self.update_native_charts()   # 3. 原生图表数据源逐个更新
    self.ai_generate_summary()    # 4. LLM生成200字洞察文本
    self.process_conditions()     # 5. 条件表达式求值动态增删页
    return self.save()            # 6. 保存最终PPT
```

**Pipeline代码位置**: [orchestrator.py - 第244-251行](file:///f:/ppt/ppt_manager_v2/orchestrator.py#L244-L251)

---

### 五、AI 智能化（LLM + Diff对比）

#### 5.1 LLM 自动生成"分析结论"

图表只能展示"是什么"，LLM帮你解释"为什么"：

```python
# ai/llm_analyst.py
prompt = "基于以下数据：{gdp}、{cpi}，200字专业分析师口吻总结本月市场"
llm.generate_analysis({
    'gdp_growth': 5.1, 
    'cpi': 0.9,
    'unemployment': 5.2
})

# 返回示例：
"""
本月宏观经济洞察：GDP增长5.1%，动能平稳。CPI同比0.9%，
通胀水平温和为货币政策留出空间。就业失业率5.2%，
青年失业率需重点关注...
"""
```

支持 **Mock模式** / **OpenAI** / **通义千问** 三种provider切换。

**代码参考**: [ai/llm_analyst.py](file:///f:/ppt/ppt_manager_v2/ai/llm_analyst.py#L1-L90)

---

## 📄 YAML V2版 配置范式参考

```yaml
project_name: "宏观经济月度分析报告"
version: "2.0"
template: "macro_analysis_template.pptx"

params:                    # 参数化生成默认值
  default_year: 2026
  default_quarter: "Q2"

anchors:                   # 锚点绑定关系
  - name: chart_gdp
    type: native_chart_update
    plugin: gdp_chart
    chart_type: line
    fallback: gdp_fallback.png

  - name: chart_cpi
    type: native_chart_update
    plugin: cpi_chart

slide_conditions:          # 条件渲染规则
  - condition: unemployment_rate > 5.1
    action: insert_slide
    position: 5

connectors:                # 多数据源配置
  mysql_stats: {type: mysql, database: macro_stats}

ai:                        # LLM配置
  provider: mock           # mock/openai/tongyi
  model: qwen-turbo

scheduler:                 # 定时调度
  cron: "0 8 1 * *"       # 每月1号早上8点
```

配置文件位置: [config/project_config_v2.yaml](file:///f:/ppt/ppt_manager_v2/config/project_config_v2.yaml)

---

## 🔧 命令行非交互模式测试

直接跑整个Pipeline验证所有环节：

```bash
cd f:\ppt\ppt_manager_v2
python -c "
import sys
sys.path.insert(0, '.')
from orchestrator import Orchestrator
orch = Orchestrator()
orch.load_template()        # 检查: 锚点扫描
result = orch.run_plugins() # 检查: 插件取数+渲染
print('插件结果:', list(result.keys()))
orch.update_native_charts() # 检查: 原生图表更新
orch.ai_generate_summary()  # 检查: LLM生成
orch.save()                 # 检查: 输出文件
print('✅ 全流程通过!')
"
```

---

## ❓ 常见问题排查

### Q1: TemplateNotFound jinja2 错误

**现象**: `jinja2.exceptions.TemplateNotFound: index_v2.html`

**已修复**: web_socket_app.py第16行明确了 template_folder 绝对路径，且文件在两处备份：
- `f:\ppt\ppt_manager_v2\templates\index_v2.html` （Flask标准位置）
- `f:\ppt\ppt_manager_v2\web\templates\index_v2.html` （配置位置）

---

### Q2: 下载文件找不到 /api/files 返回空

**已修复**: `/api/files` 和 `/download/<filename>` 两处的 `base_dir / "output"` 统一改为 `base_dir.parent / "output"` 指向 `f:\ppt\output\`。

---

### Q3: 'NoneType' object has no attribute 'text'

**现象**: 加载模板时报错

**已修复**: [orchestrator.py](file:///f:/ppt/ppt_manager_v2/orchestrator.py#L75-L90) 先判断 `if slide.shapes.title:` 再安全访问 `.text`。

---

### Q4: 插件不显示/不执行

检查两点：
1. 插件类继承 `BaseGenerator(ABC)`
2. 类属性 `generator_id` 不能是 `None`
3. 目录在 `plugins/generators/*.py` 且文件名不以 `_` 开头

---

## 📌 维护信息

| 项目 | 详情 |
|------|------|
| **版本** | V2.0 2026-05-29 |
| **入口** | `python web_socket_app.py` |
| **前端地址** | http://localhost:5001 |
| **输出目录** | `f:\ppt\output\*.pptx` |
| **日志目录** | `f:\ppt\ppt_manager_v2\logs\` |
| **核心模块** | orchestrator.py / anchor_engine.py / native_chart.py |
| **插件目录** | plugins/generators/ |