# 图表规范（原生可编辑）

所有图表必须使用 `python-pptx` 原生 `Chart` 对象创建，数据写入图表内嵌 Excel 工作簿，确保用户在 PowerPoint 中可右键 → 编辑数据。

## 支持的图表类型

| 图表类型 | XL_CHART_TYPE | 值 | 使用场景 |
|---------|---------------|-----|---------|
| 簇状柱形图 | COLUMN_CLUSTERED | 51 | 区域分布对比、团队追踪 |
| 簇状条形图 | BAR_CLUSTERED | 57 | 国家排名、负责人排名、状态漏斗（横向） |
| 折线图（带标记） | LINE_MARKERS | 65 | 多日趋势、30日追踪、7日走势 |
| 环形图 | DOUGHNUT | -4120 | 状态分布、区域占比 |
| 表格 | TABLE | 19 | 明细数据、TOP列表、状态变化 |

## 配色映射

| 用途 | 色值 | 说明 |
|------|------|------|
| 系列1主色 | `#1E3A5F` | 深蓝，主要数据系列（对应 theme primary） |
| 系列2对比 | `#ED7D31` | 橙色，对比/参考系列 |
| 系列3辅助 | `#64748B` | 灰蓝，辅助线或第三系列（对应 theme secondary） |
| 正增长 | `#10B981` | 绿色，用于涨幅标记（对应 theme accent） |
| 负增长 | `#EF4444` | 红色，用于跌幅标记（对应 theme accentNeg） |
| 警告 | `#ED7D31` | 橙色，异常告警 |

> **注意**：上表为默认配色。报告生成时 `chart_factory.py` 接受调用方传入的 `theme_colors` 参数，实际颜色由三级解析（用户主题 > 模板主题 > 默认）决定。多系列图表（如环形图/饼图）使用 `DEFAULT_COLORS` 色板：`#1E3A5F` → `#10B981` → `#ED7D31` → `#64748B` → `#EF4444`。

## 通用图表样式

1. **标题**：图表本身不设置标题（页面顶部已有文本框标题）
2. **图例**：单系列时隐藏；多系列时放置于底部
3. **数据标签**：显示数值，字体 Arial 10pt，颜色 `#333333`
4. **网格线**：仅保留水平主网格线，颜色 `#D9D9D9`，宽度 0.75pt
5. **坐标轴**：无填充、无线条；标签字体 10pt，颜色 `#666666`
6. **绘图区**：无填充、无边框
7. **图表区**：无填充、无边框

## 图表数据绑定

```python
from pptx.chart.data import ChartData
from pptx.enum.chart import XL_CHART_TYPE

chart_data = ChartData()
chart_data.categories = ['亚洲', '非洲', '拉美', '中东', '欧洲']
chart_data.add_series('数值', (2160, 1840, 1743, 878, 247))

chart = slide.shapes.add_chart(
    XL_CHART_TYPE.COLUMN_CLUSTERED,
    left, top, width, height,
    chart_data
).chart
```

数据自动写入 PPT 内嵌的 Excel 工作簿，用户可在 PowerPoint 中直接编辑。

## 特殊配置

### 条形图逆序（最大值在顶部）

```python
chart = slide.shapes.add_chart(XL_CHART_TYPE.BAR_CLUSTERED, ...).chart
chart.category_axis.reverse_order = True
```

### 环形图中心空白

```python
chart = slide.shapes.add_chart(XL_CHART_TYPE.DOUGHNUT, ...).chart
chart.plots[0].hole_size = 0.5  # 50% 中心空白
```

### 折线图标记样式

```python
chart = slide.shapes.add_chart(XL_CHART_TYPE.LINE_MARKERS, ...).chart
series = chart.series[0]
series.marker.size = 7
series.marker.style = XL_MARKER_STYLE.CIRCLE
```


## 通用图表自动选择（新增）

通用构建器支持自动选择图表类型，根据数据特征和页面场景智能推荐。

### 智能推荐规则

| 数据特征 | 推荐图表 | 原因 |
|---------|---------|------|
| 时间序列 + 数值 | LINE_MARKERS | 展示趋势变化 |
| 1个分类列 + 数值列 | BAR_CLUSTERED | 横向对比排名 |
| 1个分类列（含百分比） | DOUGHNUT | 展示占比结构 |
| 多个数值维度 | COLUMN_CLUSTERED | 多维度对比 |
| 需要展示精确数值 | TABLE | 数据明细 |
| 发现数据分层 | FUNNEL | 漏斗转化 |
| 经纬度数据 | 散点图/气泡图 | 地理分布 |

### 图表质量自检

| 检查项 | 问题 | 修复 |
|--------|------|------|
| 图表刻度异常 | Y轴从非零开始导致误导 | 重置Y轴最小值 |
| 图表无数据 | 数据系列为空 | 跳过该图表插入 |
| 表格列宽不合理 | 列宽与内容不匹配 | 按内容自适应列宽 |