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

openapi: 3.0.3
info:
  title: Financial Report Generation - Task 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: Task
    description: 任务管理
  - name: Task Progress
    description: 任务进度

paths:
  /tasks:
    get:
      summary: 查询任务列表
      tags:
        - Task
      parameters:
        - name: tenantId
          in: header
          required: true
          schema:
            type: string
        - name: status
          in: query
          schema:
            type: string
            enum: [PENDING_OUTLINE, PENDING_OUTLINE_CONFIRM, PENDING_DATA_PREPARE, PENDING_DATA_CONFIRM, PENDING_REPORT_GENERATE, GENERATING, PENDING_REVIEW, COMPLETED, FAILED, CANCELLED]
        - name: page
          in: query
          schema:
            type: integer
            default: 1
        - name: size
          in: query
          schema:
            type: integer
            default: 10
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskPageResponse'

    post:
      summary: 创建任务
      tags:
        - Task
      parameters:
        - name: tenantId
          in: header
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TaskCreateRequest'
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskResponse'

  /tasks/{taskId}:
    get:
      summary: 查询任务详情
      tags:
        - Task
      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:
                $ref: '#/components/schemas/TaskResponse'
        '404':
          description: 任务不存在

    put:
      summary: 更新任务
      tags:
        - Task
      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/TaskUpdateRequest'
      responses:
        '200':
          description: 成功

    delete:
      summary: 删除任务
      tags:
        - Task
      parameters:
        - name: taskId
          in: path
          required: true
          schema:
            type: string
        - name: tenantId
          in: header
          required: true
          schema:
            type: string
      responses:
        '200':
          description: 成功

  /tasks/{taskId}/start:
    post:
      summary: 开始任务
      tags:
        - Task
      parameters:
        - name: taskId
          in: path
          required: true
          schema:
            type: string
        - name: tenantId
          in: header
          required: true
          schema:
            type: string
      responses:
        '200':
          description: 成功

  /tasks/{taskId}/complete:
    post:
      summary: 完成任务
      tags:
        - Task
      parameters:
        - name: taskId
          in: path
          required: true
          schema:
            type: string
        - name: tenantId
          in: header
          required: true
          schema:
            type: string
      responses:
        '200':
          description: 成功

  /tasks/{taskId}/cancel:
    post:
      summary: 取消任务
      tags:
        - Task
      parameters:
        - name: taskId
          in: path
          required: true
          schema:
            type: string
        - name: tenantId
          in: header
          required: true
          schema:
            type: string
      responses:
        '200':
          description: 成功

  /tasks/{taskId}/progress:
    get:
      summary: 订阅任务进度
      tags:
        - Task Progress
      parameters:
        - name: taskId
          in: path
          required: true
          schema:
            type: string
        - name: tenantId
          in: header
          required: true
          schema:
            type: string
      responses:
        '200':
          description: 成功
          content:
            text/event-stream:
              schema:
                type: string

components:
  schemas:
    TaskCreateRequest:
      type: object
      required:
        - taskName
        - creatorId
        - creatorName
      properties:
        taskName:
          type: string
          description: 任务名称
          maxLength: 255
        description:
          type: string
          description: 任务描述
        modelConfigId:
          type: string
          description: 模型配置ID
        parameters:
          type: object
          description: 任务参数
          additionalProperties: true

    TaskUpdateRequest:
      type: object
      properties:
        taskName:
          type: string
          description: 任务名称
          maxLength: 255
        description:
          type: string
          description: 任务描述
        parameters:
          type: object
          description: 任务参数
          additionalProperties: true

    TaskResponse:
      type: object
      properties:
        taskId:
          type: string
          description: 任务ID
        tenantId:
          type: string
          description: 租户ID
        orgId:
          type: string
          description: 组织ID
        taskName:
          type: string
          description: 任务名称
        description:
          type: string
          description: 任务描述
        status:
          type: string
          description: 任务状态
          enum: [PENDING_OUTLINE, PENDING_OUTLINE_CONFIRM, PENDING_DATA_PREPARE, PENDING_DATA_CONFIRM, PENDING_REPORT_GENERATE, GENERATING, PENDING_REVIEW, COMPLETED, FAILED, CANCELLED]
        currentStage:
          type: string
          description: 当前阶段
        modelConfigId:
          type: string
          description: 模型配置ID
        creatorId:
          type: string
          description: 创建人ID
        creatorName:
          type: string
          description: 创建人名称
        progress:
          type: integer
          description: 任务进度(0-100)
        failureReason:
          type: string
          description: 失败原因
        parameters:
          type: object
          description: 任务参数
        createTime:
          type: string
          format: date-time
          description: 创建时间
        updateTime:
          type: string
          format: date-time
          description: 更新时间
        startTime:
          type: string
          format: date-time
          description: 开始时间
        endTime:
          type: string
          format: date-time
          description: 完成时间

    TaskPageResponse:
      type: object
      properties:
        code:
          type: integer
          description: 响应码
        message:
          type: string
          description: 响应消息
        data:
          type: object
          properties:
            total:
              type: integer
              description: 总数
            page:
              type: integer
              description: 当前页
            size:
              type: integer
              description: 每页大小
            records:
              type: array
              items:
                $ref: '#/components/schemas/TaskResponse'