byteplan-ppt

1. **检查数据** - 确认数据文件存在
2. **组装数据** - 将分析数据转换为 PPT 格式
3. **生成 PPT** - 使用 PptxGenJS 创建演示文稿
4. **检查质量** - 执行元素重叠检查

**设计原则**：PPT 与 HTML 风格统一，确保演示效果一致。

**前置条件**：必须先使用 [byteplan-analysis](../byteplan-analysis/SKILL.md) skill 完成数据分析。

---

## 设计规范（与 HTML 一致）

### 1. 页面结构（11页标准模板）

| 页码 | 内容 | 背景风格 |
|------|------|----------|
| 1 | 封面 | 紫色渐变 |
| 2 | 目录 | 深色渐变 |
| 3 | 核心发现摘要（三卡片） | 深蓝色渐变 |
| 4 | 关键指标概览（四卡片） | 深色渐变 |
| 5 | 数据图表1（柱状图） | 深色渐变 |
| 6 | 数据图表2（贡献率） | 深蓝色渐变 |
| 7 | 排行榜（TOP8） | 深色渐变 |
| 8 | 数据明细表 | 深色渐变 |
| 9 | 关键洞察（四卡片） | 深蓝色渐变 |
| 10 | 行动建议（四卡片） | 深色渐变 |
| 11 | 结尾页 | 紫色渐变 |

### 2. 颜色规范

```
主题色：
- purple: #667eea（主强调色）
- dark-purple: #764ba2（渐变终点色）

背景色：
- dark-bg: #1a1a2e（主背景）
- dark-bg-2: #16213e（次背景）
- dark-bg-3: #0f3460（强调背景）

文字色：
- text-white: #FFFFFF（标题文字）
- text-gray: #CBD5E1（正文文字）
- text-muted: #94A3B8（辅助文字）

数据色：
- green: #4ade80（正向数据/数值）
- blue: #60a5fa（链接/贡献率）
- pink: #f472b6（图表色）
- orange: #fbbf24（警告/排名）
- red: #f87171（负向数据）
- cyan: #06B6D4（图表色）
```

### 3. 字体规范

```
字体：微软雅黑（Microsoft YaHei）

封面标题：44pt, Bold
页面标题：28pt, Bold
卡片标题：16-26pt, Bold
正文内容：12-14pt
数据数值：22-24pt, Bold, Green
贡献率：14pt, Blue
```

### 4. 渐变背景

```
封面/结尾页：
background: linear-gradient(135deg, #667eea 0%, #764ba2 100%)

内容页（交替使用）：
background: linear-gradient(135deg, #1a1a2e 0%, #16213e 100%)
background: linear-gradient(135deg, #0f3460 0%, #16213e 100%)
background: linear-gradient(135deg, #16213e 0%, #1a1a2e 100%)
```

### 5. 卡片设计

**重要规则：洞察卡片和建议卡片使用直角（不使用圆角）**

```
基础卡片：
- 背景：rgba(255,255,255,0.1) [白色10%透明度]
- 边框：2px solid rgba(255,255,255,0.2)

洞察卡片（直角）：
- 背景：紫色/橙色透明背景（transparency: 80%）
- 左边框：5px solid #667eea（紫色）或 #fbbf24（橙色）
- 圆角：无（使用直角 rect）
- 普通洞察：紫色背景 + 紫色左边框
- 警告洞察：橙色背景 + 橙色左边框 + 橙色标题

建议卡片（直角）：
- 背景：rgba(74,222,128,0.2) [绿色20%透明度]
- 左边框：5px solid #4ade80（绿色）
- 圆角：无（使用直角 rect）
```

### 6. 图表配色

```javascript
// 柱状图颜色（与 HTML 一致）
chartColors: ['#4ade80', '#60a5fa', '#f472b6', '#667eea', '#fbbf24']

// 排行榜第一名高亮
backgroundColor: '#4ade80'  // 第一名绿色
backgroundColor: '#60a5fa'  // 第二、三名蓝色
backgroundColor: '#667eea'  // 其他紫色
```

---

## 数据格式

### 新格式（推荐）：使用 charts 数组

支持动态数量的图表，与 byteplan-html 保持一致：

```json
{
  "title": "报告标题",
  "subtitle": "副标题",
  "period": "2026年3月",
  "sections": ["章节1", "章节2"],
  "summary": [
    { "rank": "🥇 第一名", "name": "项目A", "type": "类型", "value": "¥1,000,000", "rate": "贡献率 68%" }
  ],
  "kpis": [
    { "icon": "💰", "label": "指标名称", "value": "1,000", "unit": "单位" }
  ],
  "charts": [
    {
      "title": "图表标题1",
      "type": "bar",
      "data": [{ "name": "类别A", "value": 100 }]
    },
    {
      "title": "图表标题2",
      "type": "horizontalBar",
      "data": [{ "name": "类别A", "value": 68 }]
    }
  ],
  "tableData": {
    "title": "明细表",
    "columns": ["列1", "列2"],
    "rows": [["值1", "值2"]]
  },
  "insights": [
    { "title": "洞察标题", "content": "洞察内容", "warning": false }
  ],
  "recommendations": [
    { "title": "建议标题", "content": "建议内容" }
  ],
  "source": "BytePlan 数据平台"
}
```

**图表类型说明**：

| type 值 | 图表类型 | 说明 |
|---------|----------|------|
| `"bar"` | 柱状图 | 默认类型，适合数值对比 |
| `"horizontalBar"` | 横向条形图 | 适合排行榜、百分比展示 |
| `"ranking"` | 排行榜 | 第一名绿色高亮，第二三名蓝色 |

### 旧格式（向后兼容）

```json
{
  "title": "报告标题",
  "subtitle": "副标题",
  "period": "2026年3月",
  "sections": ["章节1", "章节2", "章节3", "章节4"],
  "summary": [
    { "rank": "🥇 第一名", "name": "项目A", "type": "类型", "value": "¥1,000,000", "rate": "贡献率 68%" }
  ],
  "kpis": [
    { "icon": "💰", "label": "指标名称", "value": "1,000", "unit": "单位" }
  ],
  "barChart": {
    "title": "图表标题",
    "data": [{ "name": "类别A", "value": 100 }]
  },
  "ratioData": {
    "title": "贡献率标题",
    "data": [{ "name": "类别A", "value": 68 }]
  },
  "rankingData": {
    "title": "排行榜标题",
    "data": [{ "name": "项目A", "value": 100 }]
  },
  "tableData": {
    "title": "明细表",
    "columns": ["列1", "列2"],
    "rows": [["值1", "值2"]]
  },
  "insights": [
    { "title": "洞察标题", "content": "洞察内容", "warning": false }
  ],
  "recommendations": [
    { "title": "建议标题", "content": "建议内容" }
  ],
  "source": "BytePlan 数据平台"
}
```

**注意**：推荐使用新的 `charts` 数组格式，更灵活且与 HTML 报告统一。

---

## 使用方法

### 方式一：命令行

```bash
# 使用默认数据文件 (ppt_data.json)
cd skills/byteplan-ppt
pnpm run generate -o report.pptx

# 指定数据文件
pnpm run generate -o report.pptx -d /path/to/data.json

# 检查质量
pnpm run check report.pptx
```

### 方式二：Node.js 调用

```javascript
import { generatePpt } from './scripts/generate_ppt.js';

generatePpt('report.pptx', 'data.json');
```

---

## 完整示例

### 1. 准备数据文件

```bash
# 从分析结果生成数据文件
# 确保 ppt_data.json 包含所有必要字段
```

### 2. 生成 PPT

```bash
cd skills/byteplan-ppt
pnpm run generate -o 边际贡献分析报告.pptx -d ../ppt_data.json
```

### 3. 检查质量

```bash
pnpm run check 边际贡献分析报告.pptx
```

### 4. 打开查看

```bash
open 边际贡献分析报告.pptx
```

---

## 与 HTML 风格对照

| 元素 | HTML | PPT |
|------|------|-----|
| 封面背景 | 紫色渐变 #667eea → #764ba2 | 相同 |
| 内容页背景 | 深色渐变 #1a1a2e → #16213e | 相同 |
| 字体 | 微软雅黑 | 微软雅黑 |
| 标题字号 | 44px (封面) / 28px (页面) | 44pt / 28pt |
| 卡片样式 | 圆角 + 半透明背景 | 相同 |
| 数据颜色 | 绿色 #4ade80 | 相同 |
| 图表配色 | 5色循环 | 相同 |
| 洞察卡片 | 左边框紫色/橙色 | 相同 |
| 建议卡片 | 左边框绿色 | 相同 |

---

## 完整示例

### 示例：跨境电商边际贡献分析

本案例展示如何使用 BytePlan 平台数据生成完整的 PPT 报告。

#### 1. 准备数据文件

参考示例数据文件：`examples/margin-contribution-analysis.json`

```bash
# 复制示例数据
cp examples/margin-contribution-analysis.json ppt_data.json
```

#### 2. 生成 PPT

```bash
cd skills/byteplan-ppt
pnpm run generate -o 边际贡献分析报告.pptx
```

#### 3. 检查质量

```bash
pnpm run check 边际贡献分析报告.pptx
```

#### 4. 预期输出

生成的 PPT 包含以下内容：

| 页码 | 内容 | 说明 |
|------|------|------|
| 1 | 封面 | 紫色渐变背景，标题"跨境电商边际贡献分析报告" |
| 2 | 目录 | 8个章节的双列布局 |
| 3 | 核心发现摘要 | 三卡片展示：天猫(第一名)、CD120P(第二名)、美国(第三名) |
| 4 | 关键指标概览 | 四卡片KPI：最大贡献、最高贡献率、核心市场、风险项 |
| 5 | 渠道边际贡献对比 | 5个渠道的柱状图对比 |
| 6 | 渠道贡献率对比 | 横向条形图展示各渠道贡献率 |
| 7 | TOP8排行榜 | 横向条形图，第一名绿色高亮 |
| 8 | 数据明细表 | 8条记录的明细表，负值红色显示 |
| 9 | 关键洞察 | 四卡片：三个发现 + 一个风险提示(橙色边框) |
| 10 | 行动建议 | 四卡片(绿色边框) |
| 11 | 结尾页 | 紫色渐变背景，"谢谢观看" |

#### 5. 示例数据结构

```json
{
  "title": "跨境电商边际贡献分析报告",
  "subtitle": "找出贡献最大的要素",
  "period": "2026年3月31日",
  "sections": ["核心发现摘要", "关键指标概览", ...],
  "summary": [
    { "rank": "🥇 第一名", "name": "天猫", "type": "渠道", "value": "¥16,273,934", "rate": "贡献率 68%" }
  ],
  "kpis": [
    { "icon": "💰", "label": "最大边际贡献", "value": "16,273,934", "unit": "元（天猫）" }
  ],
  "barChart": {
    "title": "渠道边际贡献对比",
    "data": [{ "name": "天猫", "value": 16273934 }]
  },
  "ratioData": {
    "title": "渠道边际贡献率对比",
    "data": [{ "name": "天猫", "value": 68 }]
  },
  "rankingData": {
    "title": "边际贡献 TOP8 排行榜",
    "data": [{ "name": "天猫 (渠道)", "value": 16273934 }]
  },
  "tableData": {
    "title": "边际贡献明细表",
    "columns": ["要素名称", "类型", "收入(元)", "边际贡献(元)", "贡献率"],
    "rows": [["天猫", "渠道", "17,742,456", "16,273,934", "68%"]]
  },
  "insights": [
    { "title": "天猫渠道表现卓越", "content": "以68%贡献率成为最大贡献来源。", "warning": false },
    { "title": "⚠️ 存在亏损产品", "content": "CD130P-B和CD140P边际贡献为负。", "warning": true }
  ],
  "recommendations": [
    { "title": "加大天猫渠道投入", "content": "增加营销预算和运营资源。" }
  ],
  "source": "BytePlan 数据平台 · 跨境电商租户"
}
```

---

## 注意事项

- **字体要求**：必须使用微软雅黑，确保中英文显示效果
- **PPT 页数**：标准 11 页
- **元素检查**：生成后必须执行重叠检查
- **与 HTML 一致**：设计风格与 byteplan-html 完全统一
- **包管理器**：使用 pnpm 安装依赖