switch to poi-tl for template rendering, add OpenAPI spec

- Replace manual DOCX ZIP manipulation with poi-tl library - Templates use {{variable}} syntax, editable in Word - Add postProcess hook for dynamic content (table rows) - Clean up unused generate() method from TemplateProvider - Remove custom ExportResult/ExportFileWriter complexity - Add docs/openapi.yaml — OpenAPI 3.1 spec for export API
2026-05-08 11:53:43 +08:00
parent 180c8e78aa
commit 7b79f1f551
6 changed files with 235 additions and 76 deletions
@@ -0,0 +1,138 @@
+openapi: "3.1.0"
+info:
+  title: GMP Mock Service API
+  description: |
+    Mock 服务，提供基于 Word 模板的文档导出功能。
+    模板使用 poi-tl 的 `{{variable}}` 语法标记占位符，
+    业务数据通过 `businessData` 传入。
+  version: "1.0.0"
+  contact:
+    name: closein
+servers:
+  - url: http://localhost:6666
+    description: 本地开发服务器
+
+paths:
+  /api/docx/export:
+    post:
+      summary: 导出 Word 文档
+      description: |
+        根据模板 ID 选择模板，填充业务数据后流式返回 `.docx` 文件。
+
+        请求成功时直接流式下载文件，失败时返回 JSON 错误体。
+      operationId: exportDocx
+      tags:
+        - Docx Export
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/DocxExportRequest'
+            example:
+              exportId: "annualReport"
+              businessData: {}
+      responses:
+        "200":
+          description: 成功 — 流式下载 `.docx` 文件
+          content:
+            application/vnd.openxmlformats-officedocument.wordprocessingml.document:
+              schema:
+                type: string
+                format: binary
+          headers:
+            Content-Disposition:
+              schema:
+                type: string
+                example: 'attachment; filename="annualReport.docx"'
+              description: 文件名，格式为 `attachment; filename="<模板名>.docx"`
+        "400":
+          description: 参数校验失败
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ApiError'
+              example:
+                code: 400
+                msg: "exportId 不能为空; businessData 不能为空"
+        "404":
+          description: 模板不存在
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ApiError'
+              example:
+                code: 404
+                msg: "模板不存在: unknownTemplate"
+        "500":
+          description: 服务器内部错误（文档生成失败）
+
+components:
+  schemas:
+    DocxExportRequest:
+      type: object
+      required:
+        - exportId
+        - businessData
+      properties:
+        exportId:
+          type: string
+          description: 模板标识，例如 `"annualReport"`
+          example: "annualReport"
+        businessData:
+          type: object
+          description: |
+            业务数据键值对，用于填充模板中的变量。
+            当前模板自行定义默认值，后续可改为从此处读取。
+          example: {}
+      additionalProperties: false
+
+    ApiError:
+      type: object
+      required:
+        - code
+        - msg
+      properties:
+        code:
+          type: integer
+          description: 错误码
+          example: 400
+        msg:
+          type: string
+          description: 错误描述
+          example: "exportId 不能为空"
+
+    # --- 模板定义（非 OpenAPI 标准，用于文档参考） ---
+
+    Template:
+      type: object
+      description: 可用模板
+      properties:
+        exportId:
+          type: string
+          description: 模板标识
+          example: "annualReport"
+        fileName:
+          type: string
+          description: 生成的文件名
+          example: "annualReport.docx"
+        variables:
+          type: array
+          description: 模板中可用的占位符变量
+          items:
+            type: string
+          example:
+            - "{{title}}"
+            - "{{companyName}}"
+            - "{{reportPeriod}}"
+            - "{{generatedDate}}"
+
+x-templates:
+  - exportId: "annualReport"
+    fileName: "annualReport.docx"
+    description: 年度工作报告模板，包含标题、公司信息、表格（3 行数据）
+    variables:
+      - title
+      - companyName
+      - reportPeriod
+      - generatedDate