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: []