erpnew/api_v1/views/printing/API.md

Printing API 文档

概述

本文档详细描述了 printing 模块下的所有 API 接口，包括印染订单 (PrintingOrder)、印染任务 (PrintingJob) 和开版订单 (PlateOrder) 的管理。

基础 URL

所有 printing 相关 API 都在以下基础路径下：

/api/v1/

认证与权限

• 所有接口都需要 JWT 认证。
• PrintingOrder 和 PrintingJob 接口需要用户是印染工厂类型商户 (MerchantTypeEnum.FACTORY)。
• PlateOrder 接口无此限制，但作废/恢复等操作需要特定权限。

---

1. Printing Orders API (印染订单)

基础路径: /api/v1/printing-orders/

管理印染生产的主订单。

1.1. 标准操作 (CRUD)

• GET /api/v1/printing-orders/

  • 描述: 获取印染订单列表。
  • 查询参数:
    • customer: 客户ID
    • customer_name: 客户名称 (模糊查询)
    • customer_phone: 客户电话 (模糊查询)
    • fabric: 面料 (模糊查询)
    • is_urgent: 是否紧急 (true/false)
    • is_fabric_received: 布料是否已收 (true/false)
    • is_invalid: 是否作废 (true/false)
    • area: 地区 (模糊查询)
    • outgoing_date_from/to: 出货日期时间范围（支持传 YYYY-MM-DD 或日期时间；to 传日期时表示包含整天）
    • created_date_from/to: 创建日期范围
    • search: 全文搜索 (客户名称, 面料, 地区, 工艺)
    • ordering: 排序字段 (e.g., -created_at)
  • 响应: PrintingOrderListSerializer 列表。

• GET /api/v1/printing-orders/{id}/

  • 描述: 获取单个印染订单详情。
  • 响应: PrintingOrderDetailSerializer。

• POST /api/v1/printing-orders/

  • 描述: 创建一个新的印染订单。
  • 请求体: PrintingOrderCreateUpdateSerializer。

• PUT/PATCH /api/v1/printing-orders/{id}/

  • 描述: 完全或部分更新一个印染订单。
  • 请求体: PrintingOrderCreateUpdateSerializer。
  • 注意: 如果订单下已有开始的 PrintingJob，则无法修改 process 字段。

• DELETE /api/v1/printing-orders/{id}/

  • 描述: 已禁用。请使用 invalidate 接口作废订单。

1.2. 自定义操作 (Custom Actions)

• POST /api/v1/printing-orders/{id}/invalidate/

  • 描述: 作废订单。需要 printing.can_invalidate_printingorder 权限。

• POST /api/v1/printing-orders/{id}/activate/

  • 描述: 恢复已作废的订单。需要 printing.can_activate_printingorder 权限。

• POST /api/v1/printing-orders/{id}/mark_fabric_received/

  • 描述: 标记订单的布料已收到。

---

2. Printing Jobs API (印染任务)

基础路径: /api/v1/printing-jobs/

管理印染订单下的具体生产任务（款式明细）。

2.1. 标准操作 (CRUD)

• GET /api/v1/printing-jobs/

  • 描述: 获取印染任务列表。
  • 查询参数:
    • printing_order: 印染订单ID
    • product: 产品ID
    • product_name: 产品名称 (模糊查询)
    • unit: 单位 (模糊查询)
    • quantity_min/max: 数量范围
    • pieces_min/max: 件数范围
    • search: 全文搜索 (产品名称, 单位, 尺寸, 备注)
    • ordering: 排序字段。
  • 响应: PrintingJobListSerializer 列表。
    • 重要变更: 列表中已包含 business_object_id 字段。

• GET /api/v1/printing-jobs/{id}/

  • 描述: 获取单个印染任务详情。
  • 响应: PrintingJobDetailSerializer。
    • 重要变更: business_object_id 字段现在会安全地返回 null 而不是报错（当 business_object 不存在时）。

• POST /api/v1/printing-jobs/

  • 描述: 创建一个新的印染任务。
  • 请求体: PrintingJobCreateUpdateSerializer。

• PUT/PATCH /api/v1/printing-jobs/{id}/

  • 描述: 完全或部分更新一个印染任务。
  • 请求体: PrintingJobCreateUpdateSerializer。

• DELETE /api/v1/printing-jobs/{id}/

  • 描述: 已禁用。

2.2. 状态流转操作 (便捷包装)

这些接口是对 stateflow 模块的包装，前端只需提供 printing_job 的 ID。

重要变更 (v2): 现在支持传递状态参数！

• POST /api/v1/printing-jobs/{id}/advance-to-next-state/

  • 描述: 将任务推进到下一个流程状态。
  • 请求体: (可选，但如果下一个状态有必填参数，则必须提供)

    {
      "parameters": {
        "temperature": "25.5",
        "operator": "张三",
        "humidity": "60%"
      }
    }
    

  • 参数说明:
    • parameters: 可选的字典，包含状态参数的键值对
    • 如果流程节点定义了必填参数（is_required=True），则必须在 parameters 中提供
    • 参数值统一为字符串类型
  • 成功响应: 200 OK

    {
      "detail": "已完成状态: 待印染",
      "data": {
        "id": 1,
        "status": "印染中",
        "business_object_id": 10,
        ...
      }
    }
    

  • 失败响应:
    • 400 Bad Request - 缺少必填参数

      {
        "detail": "缺失必填参数: temperature, operator"
      }
      

    • 400 Bad Request - 流程已完成

      {
        "detail": "流程已完成，无法继续推进"
      }
      

    • 400 Bad Request - 没有关联的流程实例

      {
        "detail": "该任务没有关联的流程实例"
      }
      

• POST /api/v1/printing-jobs/{id}/step-back-one-state/

  • 描述: 将任务回退到上一个流程状态。
  • 响应: 成功时返回 200 OK，包含 detail 和 data。失败时返回 400 Bad Request。

2.3. 状态查询操作

• GET /api/v1/printing-jobs/{id}/completed-states/

  • 描述: 查询已完成的流程节点列表。
  • 查询参数:
    • include_cancelled: 是否包含已撤销的记录 (true/false)。
  • 响应: 包含状态日志列表。

• GET /api/v1/printing-jobs/{id}/timeline/

  • 描述: 获取完整的流程时间线，包含所有节点及其状态 (not_started, in_progress, completed)。

---

3. Plate Orders API (开版订单)

基础路径: /api/v1/plate-orders/

管理设计、打样、开版的订单。

3.1. 标准操作 (CRUD)

• GET /api/v1/plate-orders/

  • 描述: 获取开版订单列表。
  • 查询参数:
    • customer_name/phone: 客户名称/电话 (模糊查询)
    • salesperson/merchandiser: 业务员/跟单员 ID
    • plate_type, urgency_level, fabric, style_name: 模糊查询
    • is_invalid, is_ordered, is_mark_frame: 布尔过滤
    • plate_date_from/to: 开版日期范围
    • required_completion_date_from/to: 要求完成时间范围（ISO8601，含具体时间）
    • created_date_from/to: 创建日期范围
    • search: 全文搜索 (设计编号, 款式名称, 客户名称, 面料)
    • ordering: 排序字段。
  • 响应: PlateOrderListSerializer 列表。

• GET /api/v1/plate-orders/{id}/

  • 描述: 获取单个开版订单详情。
  • 响应: PlateOrderDetailSerializer。
    • 重要变更: business_object_id 字段现在会安全地返回 null 而不是报错。

• POST /api/v1/plate-orders/

  • 描述: 创建一个新的开版订单。
  • 请求体: PlateOrderCreateUpdateSerializer。
  • 字段补充: image_name（可空字符串）用于记录上传的开版图片名称，即使未上传文件也可单独填写。

• PUT/PATCH /api/v1/plate-orders/{id}/

  • 描述: 完全或部分更新一个开版订单。
  • 请求体: PlateOrderCreateUpdateSerializer。
  • 字段补充: 支持更新 image_name，便于修正或补录图片名称。

• DELETE /api/v1/plate-orders/{id}/

  • 描述: 已禁用。

3.2. 自定义操作

• POST /api/v1/plate-orders/{id}/invalidate/

  • 描述: 作废开版订单。需要 printing.can_invalidate_plateorder 权限。

• POST /api/v1/plate-orders/{id}/activate/

  • 描述: 恢复已作废的开版订单。需要 printing.can_activate_plateorder 权限。

3.3. 状态流转与查询操作

与 PrintingJob 的接口类似，提供对 stateflow 的便捷包装。

重要变更 (v2): 现在支持传递状态参数！

• POST /api/v1/plate-orders/{id}/advance-to-next-state/

  • 描述: 推进到下一个流程状态。
  • 请求体: (可选，但如果下一个状态有必填参数，则必须提供)

    {
      "parameters": {
        "inspector": "李四",
        "quality_score": "95",
        "notes": "质量良好"
      }
    }
    

  • 参数说明:
    • parameters: 可选的字典，包含状态参数的键值对
    • 如果流程节点定义了必填参数（is_required=True），则必须在 parameters 中提供
    • 参数值统一为字符串类型
  • 成功响应: 200 OK

    {
      "detail": "已完成状态: 待画图",
      "data": {
        "id": 1,
        "status": "画图完成",
        "business_object_id": 20,
        ...
      }
    }
    

  • 失败响应:
    • 400 Bad Request - 缺少必填参数

      {
        "detail": "缺失必填参数: inspector"
      }
      

    • 400 Bad Request - 流程已完成或没有关联的流程实例

• POST /api/v1/plate-orders/{id}/step-back-one-state/

  • 描述: 回退到上一个流程状态。

• GET /api/v1/plate-orders/{id}/completed-states/

  • 描述: 查询已完成的流程节点列表。

• GET /api/v1/plate-orders/{id}/timeline/

  • 描述: 获取完整的流程时间线。

---

4. 重要变更说明 (v2)

4.1. 新增功能

4.1.1. 状态推进接口支持参数传递

影响接口:

• POST /api/v1/printing-jobs/{id}/advance-to-next-state/
• POST /api/v1/plate-orders/{id}/advance-to-next-state/

变更内容:

• 这两个接口现在支持在请求体中传递 parameters 字典
• parameters 是可选的，但如果流程节点定义了必填参数，则必须提供
• 参数格式与 stateflow 模块的原始接口保持一致

迁移指南:

• 旧代码（无参数）:

  POST /api/v1/printing-jobs/123/advance-to-next-state/
  // 空请求体
  

• 新代码（带参数）:

  POST /api/v1/printing-jobs/123/advance-to-next-state/
  {
    "parameters": {
      "temperature": "25.5",
      "operator": "张三"
    }
  }
  

• 向后兼容: 如果流程节点没有必填参数，可以不传 parameters，保持原有调用方式。

4.1.2. business_object_id 字段增强

影响接口:

• GET /api/v1/printing-jobs/ (列表)
• GET /api/v1/printing-jobs/{id}/ (详情)
• GET /api/v1/plate-orders/{id}/ (详情)

变更内容:

• PrintingJobListSerializer 现在包含 business_object_id 字段（之前缺失）
• PrintingJobDetailSerializer 和 PlateOrderDetailSerializer 的 business_object_id 字段已修复
• 当 business_object 不存在时，返回 null 而不是报错

迁移指南:

• 旧代码可能需要处理字段缺失或错误
• 新代码可以安全地访问 business_object_id，值可能为 null 或整数

4.2. Bug 修复

1. 修复了 business_object_id 字段在关联对象不存在时抛出异常的问题

   • 之前: 使用 source='business_object.id' 导致 AttributeError
   • 现在: 使用 SerializerMethodField 安全返回 null

2. 修复了状态推进接口无法传递参数的问题

   • 之前: 参数被忽略，导致有必填参数的流程无法推进
   • 现在: 参数正确传递到底层 stateflow 服务

4.3. 测试覆盖

新增测试用例:

• test_advance_with_parameters: 测试带参数推进
• test_advance_with_required_parameters_missing: 测试缺少必填参数的错误处理
• test_advance_with_partial_required_parameters: 测试部分提供必填参数的错误处理

4.4. 对前端的影响

必须更新的地方:

1. 如果前端代码访问 PrintingJob 列表的 business_object_id，现在会正常返回（之前可能报错或不存在）。
2. 如果前端需要在推进状态时传递参数，现在可以在请求体中添加 parameters 字段。

可选更新的地方:

1. 建议添加错误处理逻辑，当推进失败时显示具体的缺失参数信息。
2. 建议在推进前查询节点的参数要求（通过 stateflow 的 next_pending_state 接口）。

示例代码:

// 推进前查询下一个节点的参数要求
const response = await fetch(`/api/v1/stateflow/business-objects/${businessObjectId}/next_pending_state/`);
const nextState = await response.json();

if (nextState.parameters && nextState.parameters.length > 0) {
  // 显示参数输入表单
  const requiredParams = nextState.parameters.filter(p => p.is_required);
  // ... 收集用户输入
}

// 推进状态（带参数）
const advanceResponse = await fetch(`/api/v1/printing-jobs/${jobId}/advance-to-next-state/`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    parameters: collectedParameters
  })
});