gmp-service/docs/api.md

Docx Export API

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

---

POST /api/docx/export

Request

Content-Type: application/json

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

字段说明

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

示例

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)

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

可能的原因:

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

模板不存在 (HTTP 404)

{
  "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 管理，仓库只存指针。