openapi: 3.0.0
info:
  title: 印染任务流程管理 API
  description: 印染任务的流程状态管理接口
  version: 1.0.0

servers:
  - url: /api/v1
    description: API v1

paths:
  /printing-jobs/{id}/advance-to-next-state/:
    post:
      summary: 推进到下一个状态
      description: 将印染任务推进到下一个流程状态
      operationId: advanceToNextState
      tags:
        - PrintingJob Workflow
      parameters:
        - name: id
          in: path
          required: true
          description: 印染任务ID
          schema:
            type: integer
      responses:
        '200':
          description: 推进成功
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                    description: 操作结果消息
                    example: "已完成状态: 打纸"
                  data:
                    $ref: '#/components/schemas/PrintingJobDetail'
        '400':
          description: 请求错误
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                    example: "该任务没有关联的流程实例"
        '403':
          description: 权限不足
        '404':
          description: 任务不存在

  /printing-jobs/{id}/step-back-one-state/:
    post:
      summary: 回退一步
      description: 将印染任务回退到上一个流程状态
      operationId: stepBackOneState
      tags:
        - PrintingJob Workflow
      parameters:
        - name: id
          in: path
          required: true
          description: 印染任务ID
          schema:
            type: integer
      responses:
        '200':
          description: 回退成功
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                    description: 操作结果消息
                    example: "已回退状态: 滚筒"
                  data:
                    $ref: '#/components/schemas/PrintingJobDetail'
        '400':
          description: 请求错误
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                    example: "当前没有任何状态流转记录，无法回退"
        '403':
          description: 权限不足
        '404':
          description: 任务不存在

  /printing-jobs/{id}/completed-states/:
    get:
      summary: 查询已完成的流程列表
      description: 获取印染任务已完成的流程状态列表
      operationId: getCompletedStates
      tags:
        - PrintingJob Workflow
      parameters:
        - name: id
          in: path
          required: true
          description: 印染任务ID
          schema:
            type: integer
        - name: include_cancelled
          in: query
          required: false
          description: 是否包含已撤销的流程记录
          schema:
            type: boolean
            default: false
      responses:
        '200':
          description: 查询成功
          content:
            application/json:
              schema:
                type: object
                properties:
                  count:
                    type: integer
                    description: 已完成状态数量
                    example: 2
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/CompletedState'
        '403':
          description: 权限不足
        '404':
          description: 任务不存在

  /printing-jobs/{id}/timeline/:
    get:
      summary: 获取流程时间线
      description: 获取印染任务的完整流程时间线，包括未开始、进行中和已完成的状态（不包含已撤销的记录）
      operationId: getTimeline
      tags:
        - PrintingJob Workflow
      parameters:
        - name: id
          in: path
          required: true
          description: 印染任务ID
          schema:
            type: integer
      responses:
        '200':
          description: 查询成功
          content:
            application/json:
              schema:
                type: object
                properties:
                  count:
                    type: integer
                    description: 流程节点总数
                    example: 3
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/TimelineItem'
        '403':
          description: 权限不足
        '404':
          description: 任务不存在

components:
  schemas:
    PrintingJobDetail:
      type: object
      description: 印染任务详情
      properties:
        id:
          type: integer
          description: 任务ID
          example: 29
        printing_order:
          type: integer
          description: 印染订单ID
          example: 50
        printing_order_id:
          type: string
          description: 印染订单人类可读ID
          example: "20251113000050"
        product:
          type: integer
          description: 产品ID
          example: 123
        product_name:
          type: string
          description: 产品名称
          example: "纯棉布料"
        product_code:
          type: string
          description: 产品编码
          example: "P20230001"
        quantity:
          type: integer
          description: 数量
          example: 1000
        unit:
          type: string
          description: 单位
          example: "米"
        size:
          type: string
          nullable: true
          description: 一段尺寸
          example: "100x200"
        pieces:
          type: integer
          nullable: true
          description: 件数
          example: 10
        description:
          type: string
          nullable: true
          description: 备注
          example: "特殊工艺要求"
        status:
          type: string
          description: 当前状态名称
          example: "滚筒"
        status_id:
          type: integer
          nullable: true
          description: 当前状态ID
          example: 97
        is_completed:
          type: boolean
          description: 是否已完成
          example: false
        has_started:
          type: boolean
          description: 是否已开始
          example: true
        business_object_id:
          type: integer
          nullable: true
          description: 流程实例ID
          example: 29
        created_at:
          type: string
          format: date-time
          description: 创建时间
          example: "2025-11-13T07:30:00Z"
        updated_at:
          type: string
          format: date-time
          description: 更新时间
          example: "2025-11-13T07:33:00Z"

    CompletedState:
      type: object
      description: 已完成的状态记录
      properties:
        id:
          type: integer
          description: 记录ID
          example: 45
        state_id:
          type: integer
          description: 状态ID
          example: 96
        state_name:
          type: string
          description: 状态名称
          example: "打纸"
        completed_at:
          type: string
          format: date-time
          description: 完成时间
          example: "2025-11-13T07:33:00.230958Z"
        completed_by:
          type: string
          nullable: true
          description: 完成人用户名
          example: "admin"
        completed_by_name:
          type: string
          nullable: true
          description: 完成人姓名
          example: "张三"
        is_cancelled:
          type: boolean
          description: 是否已撤销
          example: false
        cancelled_at:
          type: string
          format: date-time
          nullable: true
          description: 撤销时间
          example: null

    TimelineItem:
      type: object
      description: 流程时间线项
      properties:
        state_id:
          type: integer
          description: 状态ID
          example: 96
        state_name:
          type: string
          description: 状态名称
          example: "打纸"
        state_description:
          type: string
          nullable: true
          description: 状态描述
          example: "打印纸样"
        order:
          type: integer
          description: 状态顺序
          example: 1
        status:
          type: string
          description: 状态状态
          enum:
            - not_started
            - in_progress
            - completed
          example: "completed"
        completed_at:
          type: string
          format: date-time
          nullable: true
          description: 完成时间（仅当 status=completed 时有值）
          example: "2025-11-13T07:33:00.230958Z"
        completed_by:
          type: string
          nullable: true
          description: 完成人用户名（仅当 status=completed 时有值）
          example: "admin"
        completed_by_name:
          type: string
          nullable: true
          description: 完成人姓名（仅当 status=completed 时有值）
          example: "张三"

  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

security:
  - BearerAuth: []
