data-chart-tool/API.md

# 📡 数据可视化图表生成器 - API 文档

> 版本：v1.9.0 | 基础地址：`http://192.168.0.101:16016`

---

## 接口总览

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/api/chart` | 生成图表图片（JSON body，推荐） |
| GET | `/api/chart` | 生成图表图片（URL 参数） |
| POST | `/api/combine` | 多图合并（横排/竖排）生成一张图 |
| GET | `/api/health` | 健康检查 |
| GET | `/api/docs` | 返回本文档（JSON） |

---

## 1. POST /api/chart（推荐）

通过 JSON 请求体生成图表，返回 PNG 图片。

### 请求

```
POST /api/chart
Content-Type: application/json
```

### 参数说明

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|:----:|--------|------|
| `data` | string | ✅ | — | CSV 格式数据，`\n` 换行，第一行表头，第一列横坐标 |
| `chartType` | string | — | `bar` | 图表类型：`bar` / `line` / `bar-line` / `pie` / `radar` |
| `title` | string | — | `""` | 图表标题 |
| `theme` | string | — | `default` | 主题风格：`default` / `dark` / `macarons` / `gradient` / `retro` |
| `showLegend` | boolean | — | `true` | 显示图例 |
| `showGrid` | boolean | — | `true` | 显示网格线 |
| `showLabel` | boolean | — | `false` | 显示数据标签 |
| `stackMode` | boolean | — | `false` | 堆叠模式 |
| `smoothLine` | boolean | — | `true` | 折线平滑 |
| `enableSplit` | boolean | — | `false` | 启用区域分割 |
| `splitIndex` | number | — | `3` | 分割位置（第几个数据后分割） |
| `leftLabel` | string | — | `"左侧"` | 左侧区域标签 |
| `rightLabel` | string | — | `"右侧"` | 右侧区域标签 |
| `splitStyle` | string | — | `"solid"` | 分割线样式：`solid` / `dashed` / `dotted` |
| `dualYAxis` | boolean | — | `false` | 启用双Y轴（左右量度不同） |
| `rightAxisSeries` | array | — | `null` | 右轴系列名列表，如 `["利润"]`（未列出的系列用左轴） |
| `leftAxisName` | string | — | `""` | 左轴名称（如 `"销售额(元)"`） |
| `rightAxisName` | string | — | `""` | 右轴名称（如 `"增长率(%)"`） |
| `seriesTypes` | array | — | `null` | 每系列图表类型，按系列顺序对应，如 `["bar","line"]`（`bar`/`line`/`auto`） |
| `seriesAxis` | array | — | `null` | 每系列坐标轴，按系列顺序对应，如 `[0,1]`（`0`=左轴 `1`=右轴，配合 `dualYAxis`；优先于 `rightAxisSeries`） |
| `rowsAsSeries` | boolean | — | `false` | 数据方向：`false`=列=系列（第一列是横坐标，每列一个系列）；`true`=行=系列（第一行是横坐标，每行一个系列） |
| `width` | number | — | `800` | 图片宽度（px） |
| `height` | number | — | `500` | 图片高度（px） |
| `pixelRatio` | number | — | `2` | 像素倍率（越大越清晰） |

### 返回

- **Content-Type:** `image/png`
- **响应头:**
  - `X-Chart-Width` — 图片宽度
  - `X-Chart-Height` — 图片高度
  - `X-Chart-Pixel-Ratio` — 像素倍率

### curl 示例

**基础柱状图：**
```bash
curl -X POST http://192.168.0.101:16016/api/chart \
  -H "Content-Type: application/json" \
  -d '{
    "data": "产品, Q1, Q2, Q3, Q4\n手机, 1200, 1800, 2100, 2500\n平板, 800, 950, 1100, 1300\n笔记本, 600, 750, 900, 1050",
    "chartType": "bar",
    "title": "季度销售对比"
  }' -o chart.png
```

**深色主题折线图 + 数据标签：**
```bash
curl -X POST http://192.168.0.101:16016/api/chart \
  -H "Content-Type: application/json" \
  -d '{
    "data": "月份, 营收(万), 利润(万), 用户(千)\n1月, 500, 80, 50\n2月, 680, 120, 85\n3月, 820, 160, 130\n4月, 1050, 230, 200\n5月, 1380, 350, 320",
    "chartType": "line",
    "title": "年度增长趋势",
    "theme": "dark",
    "showLabel": true,
    "width": 900,
    "height": 500
  }' -o trend.png
```

**区域分割对比图：**
```bash
curl -X POST http://192.168.0.101:16016/api/chart \
  -H "Content-Type: application/json" \
  -d '{
    "data": "月份, 方案A, 方案B\n1月, 85, 78\n2月, 88, 82\n3月, 92, 88\n4月, 90, 95\n5月, 95, 98\n6月, 98, 102",
    "chartType": "bar",
    "title": "方案对比",
    "theme": "gradient",
    "enableSplit": true,
    "splitIndex": 3,
    "leftLabel": "上半年",
    "rightLabel": "下半年",
    "splitStyle": "dashed"
  }' -o compare.png
```

**堆叠柱状图：**
```bash
curl -X POST http://192.168.0.101:16016/api/chart \
  -H "Content-Type: application/json" \
  -d '{
    "data": "季度, 线上, 线下, 批发\nQ1, 300, 200, 150\nQ2, 450, 280, 200\nQ3, 520, 350, 180\nQ4, 680, 400, 250",
    "chartType": "bar",
    "title": "渠道销售分布",
    "stackMode": true,
    "theme": "macarons"
  }' -o stack.png
```

**高分辨率大图：**
```bash
curl -X POST http://192.168.0.101:16016/api/chart \
  -H "Content-Type: application/json" \
  -d '{
    "data": "产品, 2023, 2024, 2025\nA, 100, 200, 300\nB, 150, 250, 350",
    "width": 1600,
    "height": 900,
    "pixelRatio": 3
  }' -o hd-chart.png
```

---

## 2. GET /api/chart

通过 URL 参数生成图表，适合简单场景或直接在浏览器中使用。

### 参数

| 参数 | 说明 |
|------|------|
| `data` | CSV 数据（换行用 `\n` 表示，需 URL 编码） |
| `type` | 图表类型（bar / line / bar-line） |
| `title` | 图表标题 |
| `theme` | 主题风格 |
| `width` | 图片宽度 |
| `height` | 图片高度 |

### curl 示例

```bash
curl "http://192.168.0.101:16016/api/chart?data=%E4%BA%A7%E5%93%81,Q1,Q2%0A%E6%89%8B%E6%9C%BA,100,200%0A%E5%B9%B3%E6%9D%BF,150,250&type=bar&title=%E6%B5%8B%E8%AF%95" -o chart.png
```

---

## 3. POST /api/combine（多图合并）

将**多张图表**合并到一张图片中（默认 2 张，可多张），支持**横排（单行）**、**竖排（单列）**、**多行多列网格**三种排布，返回 PNG 图片。

### 请求

```
POST /api/combine
Content-Type: application/json
```

### 参数说明

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `charts` | array | ✅ | 图表配置数组（N 张），每项同 `/api/chart` 参数：data/chartType/title/theme 等 |
| `direction` | string | 否 | `horizontal` 横排（默认）/ `vertical` 竖排 / `grid` 多行多列 |
| `cols` | number | 否 | 多行多列时的每行列数（默认 2，仅 `grid` 生效） |
| `gap` | number | 否 | 图间距（默认 24px） |
| `pixelRatio` | number | 否 | 像素倍率，默认 2（越清晰文件越大） |
| `background` | string | 否 | 背景色，默认 `#ffffff` |
| `bigTitle` | string | 否 | 整张图片的大标题（可空），居中显示在顶部 |
| `legendMode` | string | 否 | 图例方式：`own` 每个小图各自图例（默认）/ `shared-top` 共用一套图例放顶部 / `shared-bottom` 共用一套图例放底部（共用时各子图隐藏自己的图例，系列合并去重） |
| `theme` | string | 否 | 大标题/共享图例文字颜色所属主题，默认 `default`（深色用 `dark`） |

> 兼容旧参数：`chart1` + `chart2` 仍可传（等价于 `charts: [chart1, chart2]`）。

每个子图配置支持：`data`（CSV）、`chartType`（bar/line/bar-line/pie/radar）、`title`、`theme`、`showLegend`、`showGrid`、`showLabel`、`stackMode`、`smoothLine`、`width`、`height`，以及**数据方向与多类型双轴**：`rowsAsSeries`（行=系列）、`dualYAxis`、`leftAxisName`、`rightAxisName`、`seriesTypes`、`seriesAxis`。

### 高级示例（大标题 + 底部共享图例 + 行=系列 + 柱状/折线双轴）

```bash
curl -X POST http://127.0.0.1:16016/api/combine \
  -H "Content-Type: application/json" \
  -d '{
    "bigTitle": "经营总览大图",
    "legendMode": "shared-bottom",
    "direction": "grid",
    "cols": 2,
    "charts": [
      {"data": "指标, 2023, 2024, 2025\n营收(元), 1200, 1800, 2100\n销量(个), 100, 150, 130",
       "rowsAsSeries": true, "chartType": "bar", "title": "营收与销量",
       "dualYAxis": true, "leftAxisName": "元", "rightAxisName": "个",
       "seriesTypes": ["bar","line"], "seriesAxis": [0,1]},
      {"data": "产品, Q1, Q2\n手机, 1200, 1800\n平板, 800, 950", "chartType": "bar", "title": "季度销售"}
    ]
  }' -o combine.png
```

### curl 示例

**横排三张图（左右并排）：**
```bash
curl -X POST http://127.0.0.1:16016/api/combine \
  -H "Content-Type: application/json" \
  -d '{
    "charts": [
      {"data": "产品, Q1, Q2\n手机, 1200, 1800\n平板, 800, 950", "title": "销售", "chartType": "bar"},
      {"data": "月份, 营收\n1月, 500\n2月, 680\n3月, 820", "title": "趋势", "chartType": "line"},
      {"data": "地区, 销量\n华东, 300\n华南, 450", "title": "地区销量", "chartType": "bar"}
    ],
    "direction": "horizontal"
  }' -o combine.png
```  -d '{
    "chart1": {
      "data": "产品, Q1, Q2\n手机, 1200, 1800\n平板, 800, 950",
      "title": "2024年销售",
      "chartType": "bar"
    },
    "chart2": {
      "data": "月份, 营收\n1月, 500\n2月, 680\n3月, 820",
      "title": "营收趋势",
      "chartType": "line"
    },
    "direction": "horizontal"
  }' -o combine.png
```

**竖排（上下堆叠）：**
```bash
curl -X POST http://127.0.0.1:16016/api/combine \
  -H "Content-Type: application/json" \
  -d '{
    "chart1": {"data": "指标, 2023年\n营收, 500\n利润, 80", "title": "营收对比", "chartType": "bar"},
    "chart2": {"data": "月份, 效率\n1月, 85\n2月, 88", "title": "效率趋势", "chartType": "line"},
    "direction": "vertical"
  }' -o combine.png
```

### 返回

PNG 图片二进制流，响应头包含：

| 响应头 | 说明 |
|--------|------|
| `Content-Type` | `image/png` |
| `X-Combine-Direction` | `horizontal` / `vertical` |
| `X-Chart-Width` / `X-Chart-Height` | 合并图逻辑尺寸 |

---

## 4. GET /api/health

健康检查。

```bash
curl http://192.168.0.101:16016/api/health
```

返回：
```json
{
  "status": "ok",
  "service": "data-chart-tool",
  "version": "1.16.0",
  "endpoints": {
    "POST /api/chart": "生成图表图片（JSON body）",
    "GET /api/chart": "生成图表图片（URL 参数）",
    "GET /api/health": "健康检查"
  }
}
```

---

## 数据格式说明

CSV 格式，规则：

1. **第一行**：表头（系列名称）
2. **第一列**：横坐标值
3. **其余单元格**：数值
4. **分隔符**：逗号（自动识别制表符和 `|`）

```
类别, 系列1, 系列2, 系列3
A, 10, 20, 30
B, 15, 25, 35
C, 20, 30, 40
```

在 JSON 中用 `\n` 表示换行：
```json
{
  "data": "类别, 系列1, 系列2, 系列3\nA, 10, 20, 30\nB, 15, 25, 35\nC, 20, 30, 40"
}
```

---

## 各语言调用示例

### Python

```python
import requests

resp = requests.post('http://192.168.0.101:16016/api/chart', json={
    "data": "月份, 营收, 利润\n1月, 500, 80\n2月, 680, 120\n3月, 820, 160",
    "chartType": "line",
    "title": "增长趋势",
    "theme": "dark",
    "showLabel": True,
    "width": 900,
    "height": 500
})

with open('chart.png', 'wb') as f:
    f.write(resp.content)

print(f"图片大小: {len(resp.content)} bytes")
```

### JavaScript (Node.js)

```javascript
const fetch = require('node-fetch');
const fs = require('fs');

const resp = await fetch('http://192.168.0.101:16016/api/chart', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
        data: "产品, Q1, Q2\n手机, 1200, 2500\n平板, 800, 1300",
        chartType: "bar",
        title: "销售对比",
        width: 800,
        height: 500
    })
});

const buffer = await resp.buffer();
fs.writeFileSync('chart.png', buffer);
```

### JavaScript (浏览器 fetch)

```javascript
const resp = await fetch('http://192.168.0.101:16016/api/chart', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
        data: "产品, Q1, Q2\n手机, 1200, 2500\n平板, 800, 1300",
        chartType: "bar",
        title: "销售对比"
    })
});

const blob = await resp.blob();
const url = URL.createObjectURL(blob);
const img = document.createElement('img');
img.src = url;
document.body.appendChild(img);
```

### Shell (保存到文件)

```bash
curl -X POST http://192.168.0.101:16016/api/chart \
  -H "Content-Type: application/json" \
  -d '{"data":"A,B\n1,2\n3,4","chartType":"bar"}' \
  -o chart.png
```

---

## 主题预览

| 主题 | 说明 | 适用场景 |
|------|------|----------|
| `default` | 经典蓝绿配色 | 通用 |
| `dark` | 深色背景 + 高亮色 | 大屏展示、PPT |
| `macarons` | 柔和马卡龙色 | 清新风格 |
| `gradient` | 渐变色 + 圆角柱 | 现代感设计 |
| `retro` | 复古低饱和度 | 文艺风格 |

---

## 错误处理

请求失败时返回 JSON：

```json
{
  "error": "缺少 data 参数（CSV 格式数据）"
}
```

常见错误：

| HTTP 状态码 | 原因 |
|:-----------:|------|
| 400 | 缺少 `data` 参数或数据格式错误 |
| 500 | 服务端渲染异常 |

---

*文档更新时间：2026-07-16*