openapi: "3.1.0"
info:
  title: Service API
  version: "1.0.0"
  contact:
    name: 吕冬
servers:
  - url: http://193.112.146.124:6666
    description: 开发服务器

paths:
  /api/docx/export:
    post:
      summary: 导出 Word 文档
      description: |
        请求成功时返回文件流，失败时返回 JSON 错误体。
      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/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 不能为空"