gmp-service/docs/openapi.yaml

openapi: "3.1.0"
info:
  title: GMP Service API
  version: "1.1.0"
  contact:
    name: 吕冬
servers:
  - url: https://closein.site
    description: 生产服务器（HTTPS）
  - url: http://localhost:10086
    description: 本地开发服务器（HTTP）

paths:
  /api/docx/export:
    post:
      summary: 导出 Word 文档
      description: |
        接收模板 ID 和业务数据，生成 DOCX 文件并缓存。
        成功时返回 JSON，其中 url 字段用于下载文件。
      operationId: exportDocx
      tags:
        - Docx Export
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DocxExportRequest'
            example:
              exportId: "annualReport"
              businessData:
                startYear: 2023
                endYear: 2024
      responses:
        "200":
          description: 导出成功 — 返回下载链接
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiSuccessExport'
              example:
                code: 0
                msg: "success"
                data:
                  url: "https://closein.site/api/docx/download?id=d8d4122719c8465ea75ab62b37f6ce10"
                  fileName: "annualReport.docx"
        "400":
          description: 参数校验失败（exportId 为空 / businessData 为空）
          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: "模板不存在: 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，生成后 30 分钟自动过期清理。
      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:
    DocxExportRequest:
      type: object
      required:
        - exportId
        - businessData
      properties:
        exportId:
          type: string
          description: 模板标识，例如 "annualReport"
          example: "annualReport"
        businessData:
          type: object
          description: |
            业务数据键值对，用于填充模板中的变量。
            每个模板定义自己的默认值，businessData 可覆盖。
          additionalProperties:
            type: object
          example:
            startYear: 2023
            endYear: 2024

    ApiResponse:
      type: object
      description: 统一 API 响应格式
      required:
        - code
        - msg
      properties:
        code:
          type: integer
          description: 状态码（0=成功，其他=错误）
          example: 0
        msg:
          type: string
          description: 状态描述
          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: 文件下载 URL，由 origin + 路径组成
          example: "https://closein.site/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