# Flow B — Job JSON 声明式编排

使用 PptEngine 引擎，通过一个 Job JSON 文件声明全部数据源、变换、幻灯片渲染逻辑。

## 端到端流程

### Step 1: 编写 job.json

参考 [job-schema.md](job-schema.md) 了解完整结构。

最小示例:

```json
{
  "template": {"path": "aim/aim03.pptx"},
  "datasources": {},
  "slides": [
    {
      "id": "cover",
      "texts": [{"target": "标题", "value": "年度报告"}]
    }
  ],
  "output": {"path": "/tmp/output.pptx"}
}
```

### Step 2: 验证（可选）

```bash
python scripts/run_job.py job.json --dry-run
```

输出: `{"status": "ok", "message": "schema 验证通过", "slides": 1, "datasources": []}`

### Step 3: 渲染

```bash
python scripts/run_job.py job.json
```

输出: `{"status": "ok", "output": "/tmp/output.pptx"}`

引擎日志输出到 stderr。

## Flow A vs Flow B 选择矩阵

| 维度 | Flow A (generate_ppt) | Flow B (run_job) |
|------|----------------------|------------------|
| 配置格式 | config.json + CSV | job.json（含数据源声明）|
| 数据来源 | 本地 CSV | CSV/Excel/Tushare |
| 数据变换 | 手动预处理 | 声明式 ops |
| 图表创建 | 通过占位符替换 | 通过 ChartSpec |
| 文本替换 | 通过 text_data | 通过 SlideSpec.texts |
| 适用场景 | 模板已有占位符 | 从零编排 |

## 完整 job.json 示例

```json
{
  "template": {"path": "aim/aim03.pptx"},
  "datasources": {
    "ytd": {
      "type": "csv",
      "path": "/tmp/ytd_chart.csv"
    }
  },
  "transforms": {
    "ytd_sorted": {
      "from": "ytd",
      "ops": [
        {"type": "sort", "sort_by": ["日期"]}
      ]
    }
  },
  "slides": [
    {
      "id": "cover",
      "texts": [
        {"target": "标题", "value": "2024年度报告"},
        {"target": "日期", "value": "2024-12-31"}
      ]
    },
    {
      "id": "chart_page",
      "charts": [
        {
          "mode": "update",
          "target": "当年收益率走势图",
          "source": "ytd_sorted",
          "categories": "日期",
          "series": [
            {"key": "沪深300指数", "name": "沪深300", "axis": "secondary"},
            {"key": "组合收益率", "name": "收益率", "axis": "primary"}
          ]
        }
      ]
    }
  ],
  "output": {
    "path": "/tmp/report.pptx",
    "overwrite": true,
    "add_metadata": true
  }
}
```

## 已知限制

1. **图表渲染分支不完整**: engine.py 中的图表渲染仅传递基础参数（slide, data, shape_name），不传递 series_config/style_config/layout_config。复杂图表（双轴、自定义样式）建议用 Flow A。
2. 图表渲染异常会被 catch 为 warning，不会导致整个任务失败。
3. `run_job.py` 的 `--dry-run` 仅验证 JSON schema，不检查数据源是否可访问。