diff --git a/docs/api.md b/docs/api.md
new file mode 100644
index 0000000..2b3a196
--- /dev/null
+++ b/docs/api.md
@@ -0,0 +1,104 @@
+# 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 管理，仓库只存指针。