# Excel2Pic API Service

这是一个轻量级的 Excel 转图片 API 服务，专为插件化部署设计。
它使用 FastAPI 构建，底层基于 `openpyxl` 和 `Pillow` (PIL) 实现高效的表格渲染，无需依赖任何 Office 组件或浏览器环境。

## 特性

*   🚀 **高性能**：基于 FastAPI，原生异步支持。
*   📦 **极轻量**：Docker 镜像体积 < 200MB。
*   🎨 **纯 Python 实现**：无需 LibreOffice 或 Headless Chrome。
*   🔠 **中文支持**：内置宋体和黑体支持，解决中文乱码问题。
*   🐳 **一键部署**：提供 Dockerfile 和一键部署脚本。

## 目录结构

```
excel2pic/
├── app.py              # FastAPI 应用入口
├── core/               # 核心逻辑模块
│   ├── renderer.py     # 渲染引擎 (ExcelRenderer)
│   └── __init__.py
├── assets/             # 静态资源 (字体文件)
│   ├── simsun.ttc      # 宋体
│   └── simhei.ttf      # 黑体
├── tests/              # 单元测试
├── deploy.sh           # 一键部署脚本
├── Dockerfile          # Docker 构建文件
└── requirements.txt    # 项目依赖
```

## 快速开始

### 1. 本地运行

**前置条件**: Python 3.12+

```bash
# 1. 创建并激活虚拟环境
python -m venv .venv
source .venv/bin/activate  # Linux/Mac
# .venv\Scripts\activate   # Windows

# 2. 安装依赖
pip install -r requirements.txt

# 3. 启动服务
uvicorn app:app --reload
```

### 2. Docker 部署

```bash
# 赋予执行权限
chmod +x deploy.sh

# 一键构建并启动
./deploy.sh
```

## API 文档

启动服务后，访问 `http://localhost:8000/docs` 查看交互式 Swagger 文档。

### 核心接口

**POST** `/api/v1/convert`

将上传的 Excel 文件转换为 PNG 图片。

*   **参数**:
    *   `file`: (Required) Excel 文件 (.xlsx / .xls)
    *   `sheet_name`: (Optional) 指定要转换的工作表名称，默认为活动工作表。

*   **响应**:
    *   `Content-Type`: `image/png` (直接返回图片二进制流)

**示例调用 (cURL)**:

```bash
curl -X POST "http://localhost:8000/api/v1/convert" \
  -F "file=@/path/to/data.xlsx" \
  -F "sheet_name=Sheet1" \
  --output result.png
```

## 维护指南

### 添加新字体
1. 将 `.ttf` 或 `.ttc` 文件放入 `assets/` 目录。
2. 修改 `core/renderer.py` 中的 `__init__` 默认参数，或在初始化 `ExcelRenderer` 时传入路径。
3. 重新构建 Docker 镜像。

### 运行测试
```bash
export PYTHONPATH=$PYTHONPATH:.
pytest tests/
```