docs: update openapi.yaml to reflect JSON export + download endpoint

docs/openapi.yaml

@@ -1,19 +1,22 @@
 openapi: "3.1.0"
 info:
-  title: Service API
+  title: GMP Service API
-  version: "1.0.0"
+  version: "1.1.0"
   contact:
     name: 吕冬
 servers:
   - url: http://193.112.146.124:6666
-    description: 开发服务器
+    description: 生产服务器
+  - url: http://localhost:6666
+    description: 本地开发服务器
 
 paths:
   /api/docx/export:
     post:
       summary: 导出 Word 文档
       description: |
-        请求成功时返回文件流，失败时返回 JSON 错误体。
+        接收模板 ID 和业务数据，生成 DOCX 文件并缓存。
+        成功时返回 JSON，其中 url 字段用于下载文件。
       operationId: exportDocx
       tags:
         - Docx Export
@@ -25,23 +28,24 @@ paths:
               $ref: '#/components/schemas/DocxExportRequest'
             example:
               exportId: "annualReport"
-              businessData: { startYear: 2023, endYear: 2024 }
+              businessData:
+                startYear: 2023
+                endYear: 2024
       responses:
         "200":
-          description: 成功 — 流式下载文件
+          description: 导出成功 — 返回下载链接
           content:
-            application/vnd.openxmlformats-officedocument.wordprocessingml.document:
+            application/json:
               schema:
-                type: string
+                $ref: '#/components/schemas/ApiSuccessExport'
-                format: binary
+              example:
-          headers:
+                code: 0
-            Content-Disposition:
+                msg: "success"
-              schema:
+                data:
-                type: string
+                  url: "http://localhost:6666/api/docx/download?id=d8d4122719c8465ea75ab62b37f6ce10"
-                example: 'attachment; filename="annualReport.docx"'
+                  fileName: "annualReport.docx"
-              description: 文件名，格式为 `attachment; filename="<模板名>.docx"`
         "400":
-          description: 参数校验失败
+          description: 参数校验失败（exportId 为空 / businessData 为空）
           content:
             application/json:
               schema:
@@ -57,9 +61,57 @@ paths:
                 $ref: '#/components/schemas/ApiError'
               example:
                 code: 404
-                msg: "模板不存在: unknownTemplate"
+                msg: "模板不存在: ghost"
         "500":
           description: 服务器内部错误（文档生成失败）
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ApiError'
+              example:
+                code: 500
+                msg: "文档生成失败: ..."
+
+  /api/docx/download:
+    get:
+      summary: 下载缓存的 DOCX 文件
+      description: |
+        根据 export 接口返回的 key 下载已生成的 DOCX 文件。
+        key 为临时 UUID，有效期不确定（服务重启后失效）。
+      operationId: downloadDocx
+      tags:
+        - Docx Export
+      parameters:
+        - name: id
+          in: query
+          required: true
+          description: 文件缓存 key，由 export 接口返回
+          schema:
+            type: string
+            example: "d8d4122719c8465ea75ab62b37f6ce10"
+      responses:
+        "200":
+          description: 成功 — 流式下载文件
+          content:
+            application/vnd.openxmlformats-officedocument.wordprocessingml.document:
+              schema:
+                type: string
+                format: binary
+          headers:
+            Content-Disposition:
+              schema:
+                type: string
+                example: 'attachment; filename="document.docx"'
+              description: 固定为 `attachment; filename="document.docx"`
+        "404":
+          description: 文件不存在或已过期
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ApiError'
+              example:
+                code: 404
+                msg: "文件不存在或已过期: INVALID_KEY_123"
 
 components:
   schemas:
@@ -71,27 +123,72 @@ components:
       properties:
         exportId:
           type: string
-          description: 模板标识，例如 `"annualReport"`
+          description: 模板标识，例如 "annualReport"
           example: "annualReport"
         businessData:
           type: object
           description: |
             业务数据键值对，用于填充模板中的变量。
-            当前模板自行定义默认值，后续可改为从此处读取。
+            每个模板定义自己的默认值，businessData 可覆盖。
-          example: { }
+          additionalProperties:
-      additionalProperties: false
+            type: object
+          example:
+            startYear: 2023
+            endYear: 2024
 
-    ApiError:
+    ApiResponse:
       type: object
+      description: 统一 API 响应格式
       required:
         - code
         - msg
       properties:
         code:
           type: integer
-          description: 错误码
+          description: 状态码（0=成功，其他=错误）
-          example: 400
+          example: 0
         msg:
           type: string
-          description: 错误描述
+          description: 状态描述
-          example: "exportId 不能为空"
+          example: "success"
+        data:
+          type: object
+          description: 响应数据（成功时存在，失败时为 null）
+          nullable: true
+
+    ApiSuccessExport:
+      type: object
+      allOf:
+        - $ref: '#/components/schemas/ApiResponse'
+        - type: object
+          required:
+            - data
+          properties:
+            data:
+              $ref: '#/components/schemas/ExportResultData'
+
+    ExportResultData:
+      type: object
+      required:
+        - url
+        - fileName
+      properties:
+        url:
+          type: string
+          format: uri
+          description: 文件下载链接
+          example: "http://localhost:6666/api/docx/download?id=d8d4122719c8465ea75ab62b37f6ce10"
+        fileName:
+          type: string
+          description: 文件名
+          example: "annualReport.docx"
+
+    ApiError:
+      type: object
+      description: 错误响应
+      allOf:
+        - $ref: '#/components/schemas/ApiResponse'
+        - type: object
+          properties:
+            data:
+              type: null