finrep-report/backend/finrep-contract/openapi/report-api.yaml

openapi: 3.0.3
info:
  title: Financial Report Generation - Report API
  version: 1.0.0
  description: 报告管理API
servers:
  - url: http://localhost:8080/api/v1
    description: 本地开发环境
  - url: https://api.finrep.example.com/api/v1
    description: 生产环境
tags:
  - name: Report
    description: 报告管理

paths:
  /tasks/{taskId}/reports:
    get:
      summary: 查询任务报告列表
      tags:
        - Report
      parameters:
        - name: taskId
          in: path
          required: true
          schema:
            type: string
        - name: tenantId
          in: header
          required: true
          schema:
            type: string
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ReportResponse'

    post:
      summary: 创建报告
      tags:
        - Report
      parameters:
        - name: taskId
          in: path
          required: true
          schema:
            type: string
        - name: tenantId
          in: header
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReportRequest'
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReportResponse'

  /reports/{reportId}:
    get:
      summary: 查询报告详情
      tags:
        - Report
      parameters:
        - name: reportId
          in: path
          required: true
          schema:
            type: string
        - name: tenantId
          in: header
          required: true
          schema:
            type: string
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReportResponse'

    put:
      summary: 更新报告
      tags:
        - Report
      parameters:
        - name: reportId
          in: path
          required: true
          schema:
            type: string
        - name: tenantId
          in: header
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReportRequest'
      responses:
        '200':
          description: 成功

    delete:
      summary: 删除报告
      tags:
        - Report
      parameters:
        - name: reportId
          in: path
          required: true
          schema:
            type: string
        - name: tenantId
          in: header
          required: true
          schema:
            type: string
      responses:
        '200':
          description: 成功

  /reports/{reportId}/export:
    post:
      summary: 导出报告
      tags:
        - Report
      parameters:
        - name: reportId
          in: path
          required: true
          schema:
            type: string
        - name: tenantId
          in: header
          required: true
          schema:
            type: string
        - name: format
          in: query
          required: true
          schema:
            type: string
            enum: [PDF, WORD, HTML]
      responses:
        '200':
          description: 成功
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
          headers:
            Content-Disposition:
              schema:
                type: string
              description: 文件下载响应头

components:
  schemas:
    ReportRequest:
      type: object
      required:
        - title
        - format
      properties:
        title:
          type: string
          description: 报告标题
          maxLength: 255
        content:
          type: string
          description: 报告内容
        format:
          type: string
          description: 报告格式
          enum: [PDF, WORD, HTML, MARKDOWN, JSON]
        outlineId:
          type: string
          description: 关联大纲ID
        metadata:
          type: object
          description: 元数据

    ReportResponse:
      type: object
      properties:
        reportId:
          type: string
          description: 报告ID
        taskId:
          type: string
          description: 任务ID
        tenantId:
          type: string
          description: 租户ID
        title:
          type: string
          description: 报告标题
        content:
          type: string
          description: 报告内容
        format:
          type: string
          description: 报告格式
        status:
          type: string
          description: 报告状态
          enum: [DRAFT, GENERATING, COMPLETED, FAILED]
        outlineId:
          type: string
          description: 关联大纲ID
        outlineVersion:
          type: integer
          description: 大纲版本
        fileUrl:
          type: string
          description: 文件URL
        fileSize:
          type: integer
          description: 文件大小
        metadata:
          type: object
          description: 元数据
        reviewerId:
          type: string
          description: 审核人ID
        reviewerName:
          type: string
          description: 审核人名称
        reviewTime:
          type: string
          format: date-time
          description: 审核时间
        createTime:
          type: string
          format: date-time
          description: 创建时间
        updateTime:
          type: string
          format: date-time
          description: 更新时间