# Docx Export API

导出 Word 文档（.docx）接口。支持通过模板 ID 选择模板，将占位符替换为业务数据后，以流式方式返回文件。

---

## `POST /api/docx/export`

### Request

**Content-Type:** `application/json`

```json
{
  "exportId": "string (必填) - 模板标识",
  "businessData": "object (必填) - 业务数据键值对"
}
```

#### 字段说明

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `exportId` | `String` | 是 | 模板标识，例如 `"annualReport"` |
| `businessData` | `Map<String, Object>` | 是 | 用于填充模板的变量数据，目前由模板自行定义默认值 |

#### 示例

```bash
curl -OJ -X POST http://localhost:6666/api/docx/export \
  -H "Content-Type: application/json" \
  -d '{
    "exportId": "annualReport",
    "businessData": {}
  }'
```

---

### Response

#### 成功 (HTTP 200)

直接流式下载 `.docx` 文件。

| Header | 值 |
|--------|----|
| `Content-Type` | `application/vnd.openxmlformats-officedocument.wordprocessingml.document` |
| `Content-Disposition` | `attachment; filename="<模板文件名>.docx"` |

客户端收到文件流，可保存到本地或直接打开。

**curl 示例输出:**
```
HTTP/1.1 200 OK
Content-Type: application/vnd.openxmlformats-officedocument.wordprocessingml.document
Content-Disposition: attachment; filename="annualReport.docx"

<binary docx data streamed>
```

#### 参数校验失败 (HTTP 400)

```json
{
  "code": 400,
  "msg": "exportId 不能为空; businessData 不能为空"
}
```

可能的原因:
- `exportId` 为空或空白字符串
- `businessData` 为 `null`（注意：传 `"businessData": ""` 或 `"businessData": 123` 属于类型错误，Spring 会直接返回默认 400 错误）

#### 模板不存在 (HTTP 404)

```json
{
  "code": 404,
  "msg": "模板不存在: <exportId>"
}
```

#### 服务器内部错误 (HTTP 500)

文档生成过程中发生异常时返回。

---

### 可用模板

| exportId | 文件名 | 说明 |
|----------|--------|------|
| `annualReport` | `annualReport.docx` | 年度工作报告，包含标题、公司信息、数据表格 |

模板存储在 `src/main/resources/templates/` 目录下，为标准的 `.docx` 文件。模板中使用 `${variableName}` 语法标记占位符，服务端在生成时替换为实际数据。

---

### 设计要点

1. **流式输出**: 使用 Spring `StreamingResponseBody`，文档生成过程直接写入 HTTP 响应流，不经过内存缓冲，适合大文件。
2. **前置校验**: 所有参数校验（`@Valid`、模板存在性检查）在流开始前完成，出错时返回 JSON 错误响应，与正常文件流互不干扰。
3. **Git LFS**: 模板文件（`.docx`）通过 Git LFS 管理，仓库只存指针。