---
name: generate-data-report-ppt
description: >
  基于 Excel 业务明细数据，自动生成数据日报、周报、月报 PPT。
  图表使用原生 python-pptx 可编辑 Chart 对象（非 matplotlib PNG 插入）。
  当用户请求"生成日报/周报/月报"、"创建数据报告 PPT"、"输出业务报告 PPT"
  或任何涉及周期性数据报告的 PowerPoint 格式需求时触发此技能。
---

# 生成数据报告 PPT

自动生成周期性业务数据报告（日报 / 周报 / 月报）为原生可编辑 PowerPoint 文件。

## 工作流程

1. **接收输入**：数据文件路径、报告类型、日期/周期参数、可选部门/来源名称。
2. **加载数据**：`scripts/data_loader.py` 按日期范围读取 Excel 工作表，清洗并校验数据。
3. **计算指标**：`scripts/metrics_calculator.py` 根据报告类型计算 KPI、分布、趋势、告警、深度洞察。
4. **生成洞察**：`scripts/deep_insights.py` 生成结构化深度分析文本（标题 + 正文段落）。
5. **构建 PPT**：`scripts/ppt_builder.py` 从模板复制幻灯片，替换占位符，动态绘制导航标签，
   通过 `scripts/chart_factory.py` 插入原生图表、KPI 卡片、告警卡片、洞察文本块。
6. **输出**：保存 `.pptx` 文件。所有图表和表格均可在 PowerPoint 中编辑（右键 → 编辑数据）。

## 目录结构

```
generate-data-report-ppt/
├── SKILL.md
├── scripts/
│   ├── data_loader.py          # Excel 加载与数据清洗
│   ├── metrics_calculator.py   # KPI 计算引擎（含日报/周报/月报指标）
│   ├── deep_insights.py        # 结构化深度洞察生成（周报/月报各页面）
│   ├── chart_factory.py        # 原生可编辑图表创建
│   └── ppt_builder.py          # PPT 组装编排器
├── references/
│   ├── data-schema.md          # Excel 字段映射与校验规则
│   ├── report-structures.md    # 日报/周报/月报页面结构
│   ├── chart-specs.md          # 原生图表类型、配色、数据绑定
│   └── visual-style-guide.md   # 布局、字体、配色方案
└── assets/
    ├── report-master.pptx      # 日报模板（封面、内容页、目录、尾页）
    ├── weekly-master.pptx      # 周报模板
    └── monthly-master.pptx     # 月报模板
```

## 报告类型

### 日报
- **结构**：封面 → 核心指标概览 → 近10天趋势 → 订单状态分布 → 负责人分布 → 目的国家 TOP8 → 异常告警 → 今日要点
- **分析维度**：与昨日对比
- **页数**：8

### 周报
- **结构**：封面 → 周汇总 → 7日趋势 → 环比分析 → 区域分布 → 国家排行 → 团队追踪 → 问题与建议 → 下周计划
- **分析维度**：周环比（WoW）、7日移动平均
- **页数**：9
- **导航标签**：周汇总 / 趋势图 / 环比分析 / 区域排行 / 问题建议 / 下周计划

### 月报
- **结构**：封面 → 目录 → 月度总览 → 订单状态漏斗 → 区域分布 → TOP10 目的国 → 30日追踪趋势 → 团队绩效 → 支持需求分析 → 下月规划 → 尾页
- **分析维度**：环比（MoM）、同比（YoY）、日均值、结构占比
- **页数**：11
- **导航标签**：月度总览 / 订单状态 / 区域趋势 / 团队展望

## 模板使用

`assets/` 下包含三种报告模板：

| 报告类型 | 模板文件 | 包含幻灯片 |
|---------|---------|-----------|
| 日报 | `report-master.pptx` | 封面 / 内容页 / 目录页 / 尾页 |
| 周报 | `weekly-master.pptx` | 封面 / 内容页 / 目录页 / 尾页 |
| 月报 | `monthly-master.pptx` | 封面 / 内容页 / 目录页 / 尾页 |

**复制机制**：`ppt_builder._duplicate_slide(prs, source_slide)` 深度复制模板幻灯片到输出文稿。

**导航标签**：由 `ppt_builder._add_nav_tabs()` 在内容页上动态绘制，不内嵌在模板中。

## 占位符替换

所有模板形状使用 `{placeholder}` 语法。脚本遍历 `slide.shapes` 匹配段落文本进行替换。

| 占位符 | 出现位置 | 替换内容 |
|--------|---------|---------|
| `{report_title}` | 封面、内容页眉、尾页 | 如"海外订单数据日报" |
| `{report_type}` | 封面副标题 | 如"数据日报" |
| `{date}` | 封面、页眉、尾页 | 报告日期或周期 |
| `{department}` | 封面、尾页 | 如"海外事业部" |
| `{period}` | 封面、底部来源条 | 数据周期描述 |
| `{gen_time}` | 封面 | 报告生成时间 |
| `{page_title}` | 内容页 | 当前页面标题 |
| `{page_num}` | 右下角 | 如"3 / 8" |
| `{source}` | 底部来源条 | 数据来源 |
| `{kpiN_label}` / `{kpiN_value}` | 封面/尾页卡片 | 第N个指标的标签和数值 |
| `{chapterN_title}` / `{chapterN_desc}` | 目录网格 | 第N章标题和描述 |

## 图表插入规则

**严格使用原生图表**，禁止生成 matplotlib PNG 图片。

| 图表类型 | XL_CHART_TYPE | 使用场景 |
|---------|---------------|---------|
| 簇状柱形图 | COLUMN_CLUSTERED | 区域分布、团队追踪、支持需求分布 |
| 簇状条形图（横向） | BAR_CLUSTERED | 国家排名、负责人排名、状态漏斗 |
| 折线图（带标记） | LINE_MARKERS | 多日趋势（10天/7天/30天） |
| 环形图 | DOUGHNUT | 状态占比、区域占比 |
| 饼图 | PIE | 状态占比、区域占比（替代场景） |
| 表格 | TABLE | 明细列表、TOP列表、状态变化、超期订单 |

调用 `chart_factory.add_*_chart()` 传入数据数组。图表数据嵌入 PPT 内部 Excel 工作簿，用户可直接编辑。

## 数据输入要求

Excel 文件按自然日分 Sheet，工作表命名：`YYYY年MM月DD日`（如 `2026年04月10日`）。

**必填字段**：`目的国家`、`合同号`、`订单总数量`、`负责人`、`当前状态`、`拟定合同时间`

**推荐字段**：`今日进度更新`、`是否更新`、`支持需求`、`4月交付`、`5月预测`

完整字段映射、状态枚举（A-F）及校验规则见 `references/data-schema.md`。

## 配色方案

| 角色 | 色值 | 用途 |
|------|------|------|
| 主色 | `#1E3A5F` | 页眉标题、导航标签、强调色、顶部蓝线 |
| 辅色 | `#5B9BD5` | 图表主系列、CONTENTS 标签 |
| 深色背景 | `#1F3A5C` | 封面左侧块 |
| 增长色 | `#10B981` | 上涨指标、正面变化 |
| 下跌色 | `#EF4444` | 下跌指标、负面变化、严重告警 |
| 警告色 | `#ED7D31` | 中度告警、关注提示 |
| 卡片背景 | `#E7F0F7` | KPI 卡片背景 |
| 深灰文字 | `#333333` | 正文、主标题 |
| 中灰文字 | `#666666` | 副标题、次要信息 |

## 核心功能模块

### 指标计算（metrics_calculator.py）
- **日报指标**：在跟订单数、订单总量、今日更新、已发运、支持需求、下月预测、单均台数、状态分布、负责人分布、国家 TOP8、超期订单（A阶段>30天）、告警列表
- **周报指标**：周订单量、周车辆数、日均订单、单均台数、7日趋势、状态环比（WoW）、区域分布（含各国 TOP3）、国家排行（含环比变化）、团队绩效（人均产出）、支持需求分类、问题识别、下周目标（G1-G4自动生成）
- **月报指标**：月度合同数、月度车辆数、新签合同、已发运、覆盖国家数、支持需求占比、日均订单、状态漏斗（含阶段分析：前期/中期/后期）、区域分布（含各国 TOP3）、TOP10 国家（含环比变化）、30日趋势（含上中下旬均值、峰值日期）、团队绩效（人均订单/人均台数）、超期订单、下月目标（5项自动生成）、风险列表

### 深度洞察（deep_insights.py）
为周报和月报各页面生成结构化洞察文本，每条洞察包含标题和正文：
- **周报**：周内节奏分析、周环比趋势偏移、月度进度推演、关键驱动因素、区域引擎识别、结构健康度、转化效率、瓶颈诊断、库存资金占用、发运端效率、漏斗健康度、区域战略矩阵、国家组合健康度、团队人均产出、问题根因分类、目标拆解、风险对冲等
- **月报**：月度节奏、目标达成率、季节性同比、年度进度、漏斗结构诊断、区域投入 ROI、国家增速梯队、团队均衡性、支持需求趋势、下月里程碑等

### PPT 组件（ppt_builder.py）
- **KPI 卡片**：3×2 网格，支持数值、单位、变化徽章、情感标签（自动着色）
- **告警卡片**：1-3 个横向排列，支持严重/警告/关注三级颜色
- **问题卡片**：纵向堆叠，含严重度、标题、详情、建议措施
- **目标卡片**：2×2 网格，含图标、目标编号、标题、详情
- **结构化洞察文本块**：多段落洞察，自适应字号压缩以适配高度，带 emoji 前缀
- **页脚**：自动添加数据来源条和页码

## 执行示例

```python
from scripts.ppt_builder import build_daily_report, build_weekly_report, build_monthly_report
from datetime import datetime

# 日报
build_daily_report('data.xlsx', datetime(2026, 4, 10), 'daily_20260410.pptx')

# 周报（2026年第14周）
build_weekly_report('data.xlsx', 2026, 14, 'weekly_w14.pptx')

# 月报（2026年4月）
build_monthly_report('data.xlsx', 2026, 4, 'monthly_202604.pptx')
```

## 扩展技能

添加新报告类型（如季报）：
1. 在 `references/report-structures.md` 中添加页面结构定义
2. 在 `scripts/metrics_calculator.py` 中添加指标计算函数
3. 在 `scripts/deep_insights.py` 中添加洞察生成函数
4. 在 `scripts/ppt_builder.py` 中添加构建函数
5. 若内容页布局通用，无需修改模板文件