zuowei/erpnew

Fork 0

forked from erp-dev/erp

Files

colaftc cb6589c884 feat: log formatted

2026-06-26 17:03:54 +08:00

15 KiB

Raw Blame History

API v1 印染任务接口说明（printing-jobs）

本文档汇总 /api/v1/printing-jobs/ 相关接口，按当前代码实现整理，重点覆盖列表和详情接口。

基础信息

基础路径：/api/v1/printing-jobs/
资源模型：printing.PrintingJob
认证：需要已登录用户
权限：
- 用户必须属于印染工厂商户
- 常规 CRUD 受 Django model permission 控制，例如 printing.view_printingjob
- 默认按 printing_order.customer 做客户可见性过滤
- 拥有 printing.view_all_printingorders 权限可突破客户可见性限制
分页：limit/offset
- 默认 limit=800
- 最大 limit=1000

接口总览

方法	路径	说明
`GET`	`/api/v1/printing-jobs/`	获取印染任务列表
`GET`	`/api/v1/printing-jobs/{id}/`	获取印染任务详情
`POST`	`/api/v1/printing-jobs/`	创建印染任务
`PUT`	`/api/v1/printing-jobs/{id}/`	全量更新印染任务
`PATCH`	`/api/v1/printing-jobs/{id}/`	部分更新印染任务
`DELETE`	`/api/v1/printing-jobs/{id}/`	已禁用，返回 405
`POST`	`/api/v1/printing-jobs/mark-production-completed/`	显式标记任务完成生产
`POST`	`/api/v1/printing-jobs/{id}/advance-to-next-state/`	推进到下一个流程节点
`POST`	`/api/v1/printing-jobs/{id}/step-back-one-state/`	回退一个流程节点
`GET`	`/api/v1/printing-jobs/{id}/completed-states/`	查询已完成流程节点
`GET`	`/api/v1/printing-jobs/{id}/timeline/`	查询流程时间线

1. 列表

GET /api/v1/printing-jobs/

Schema 注意事项

列表响应固定为分页对象：count、next、previous、results。
results[] 中除下表特别说明外，字段会稳定返回；没有值时通常返回 null、空字符串、空数组或 false。
is_sales_order_bound 是条件字段：默认返回；当查询参数 include_sales_order_bound=false、0 或 no 时，该字段不会出现在 results[] 对象中。
列表接口不返回详情专属字段 product_code、status_id。

查询参数

参数	类型	必填	说明
`printing_order`	integer	否	按印染订单内部 ID 精确过滤
`external_order_id`	string	否	按所属订单 `external_order_id` 模糊过滤
`product`	integer	否	按产品 ID 精确过滤
`product_name`	string	否	按产品名称模糊过滤
`unit`	string	否	按单位模糊过滤
`quantity_min`	number	否	最小数量
`quantity_max`	number	否	最大数量
`pieces_min`	number	否	最小件数
`pieces_max`	number	否	最大件数
`is_production_completed`	boolean	否	是否已显式标记完成生产
`include_sales_order_bound`	boolean/string	否	是否返回 `is_sales_order_bound`；传 `false`/`0`/`no` 时不返回该字段
`search`	string	否	全文搜索：产品名称、单位、尺寸、备注
`ordering`	string	否	排序字段，支持 `id`、`created_at`、`updated_at`、`quantity`、`pieces`；前缀 `-` 表示倒序
`limit`	integer	否	每页条数，默认 800，最大 1000
`offset`	integer	否	分页偏移量

默认排序：-created_at。

响应字段

列表使用 PrintingJobListSerializer。

字段	类型	说明
`id`	integer	印染任务 ID
`original_id`	integer/null	克隆来源任务 ID；外部同步场景保存外部 record `ID`
`sub_id`	integer/null	外部明细子 ID；外部同步场景来自 `SubID`
`merchant_id`	integer/null	所属商户 ID
`printing_order`	integer	印染订单内部 ID
`printing_order_id`	string	印染订单 `human_id`
`external_order_id`	string/null	所属订单外部编号
`product`	integer	产品 ID
`product_name`	string/null	产品名称
`product_image_url`	string/null	产品主图 URL
`has_started`	boolean	是否已有未撤销流程记录
`quantity`	integer	数量
`billed_quantity`	decimal string	已关联非作废销售单明细数量合计
`unit`	string	单位
`size`	string/null	一段尺寸
`pieces`	integer/null	件数
`description`	string/null	备注
`work_state`	integer	业务进展枚举值
`work_state_display`	string	业务进展展示值
`status`	string	当前流程状态展示名
`is_completed`	boolean	流程是否完成
`is_production_completed`	boolean	是否显式标记完成生产
`progress_percentage`	number	流程进度百分比
`last_completed_state`	string	最后完成的流程节点名称
`business_object_id`	integer/null	关联流程实例 ID
`is_sales_order_bound`	boolean/可能不存在	是否已被非作废销售单明细绑定；可通过 `include_sales_order_bound=false` 关闭，关闭后字段不返回
`batch_advance_records`	array	与该任务相关的批量流程操作记录
`saleitems`	array	关联的有效销售品明细
`fabric`	string	所属印染订单面料
`created_at`	datetime	创建时间
`updated_at`	datetime	更新时间

示例

curl "http://localhost:8100/api/v1/printing-jobs/?external_order_id=KD20410611&limit=50" \
  -H "Authorization: Bearer <token>"

响应示例：

{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": 101,
      "original_id": 1190494,
      "sub_id": 1,
      "merchant_id": 1,
      "printing_order": 55,
      "printing_order_id": "20260626000055",
      "external_order_id": "KD20410611",
      "product": 88,
      "product_name": "Tj1712#12号色-24码",
      "product_image_url": null,
      "has_started": false,
      "quantity": 10,
      "billed_quantity": "0.00",
      "unit": "段",
      "size": "2.68",
      "pieces": 10,
      "description": null,
      "work_state": 0,
      "work_state_display": "生产中",
      "status": "待印染",
      "is_completed": false,
      "is_production_completed": false,
      "progress_percentage": 0.0,
      "last_completed_state": "",
      "business_object_id": 2001,
      "is_sales_order_bound": false,
      "batch_advance_records": [],
      "saleitems": [],
      "fabric": "120克本白四面弹单定",
      "created_at": "2026-06-26T15:35:00+08:00",
      "updated_at": "2026-06-26T15:35:00+08:00"
    }
  ]
}

2. 详情

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

详情使用 PrintingJobDetailSerializer，比列表多返回 product_code 和 status_id。

Schema 注意事项

详情响应是单个对象，不包在 results 中。
除下表特别说明外，字段会稳定返回；没有值时通常返回 null、空字符串、空数组或 false。
is_sales_order_bound 是条件字段：默认返回；当查询参数 include_sales_order_bound=false、0 或 no 时，该字段不会出现在响应对象中。
详情接口不返回列表专属字段 product_image_url。

路径参数

参数	类型	必填	说明
`id`	integer	是	印染任务 ID

查询参数

参数	类型	必填	说明
`include_sales_order_bound`	boolean/string	否	是否返回 `is_sales_order_bound`；传 `false`/`0`/`no` 时不返回该字段

响应字段

字段	类型	说明
`id`	integer	印染任务 ID
`original_id`	integer/null	克隆来源任务 ID；外部同步场景保存外部 record `ID`
`sub_id`	integer/null	外部明细子 ID；外部同步场景来自 `SubID`
`merchant_id`	integer/null	所属商户 ID
`printing_order`	integer	印染订单内部 ID
`printing_order_id`	string	印染订单 `human_id`
`external_order_id`	string/null	所属订单外部编号
`product`	integer	产品 ID
`product_name`	string/null	产品名称
`product_code`	string/null	产品 `human_id`
`quantity`	integer	数量
`billed_quantity`	decimal string	已关联非作废销售单明细数量合计
`unit`	string	单位
`size`	string/null	一段尺寸
`pieces`	integer/null	件数
`description`	string/null	备注
`work_state`	integer	业务进展枚举值
`work_state_display`	string	业务进展展示值
`status`	string	当前流程状态展示名
`status_id`	integer/null	当前待执行流程节点 ID；已完成时为空
`is_completed`	boolean	流程是否完成
`is_production_completed`	boolean	是否显式标记完成生产
`has_started`	boolean	是否已有未撤销流程记录
`progress_percentage`	number	流程进度百分比
`last_completed_state`	string	最后完成的流程节点名称
`business_object_id`	integer/null	关联流程实例 ID
`is_sales_order_bound`	boolean/可能不存在	是否已被非作废销售单明细绑定；可通过 `include_sales_order_bound=false` 关闭，关闭后字段不返回
`batch_advance_records`	array	与该任务相关的批量流程操作记录
`saleitems`	array	关联的有效销售品明细
`fabric`	string	所属印染订单面料
`created_at`	datetime	创建时间
`updated_at`	datetime	更新时间

示例

curl "http://localhost:8100/api/v1/printing-jobs/101/" \
  -H "Authorization: Bearer <token>"

响应示例：

{
  "id": 101,
  "original_id": 1190494,
  "sub_id": 1,
  "merchant_id": 1,
  "printing_order": 55,
  "printing_order_id": "20260626000055",
  "external_order_id": "KD20410611",
  "product": 88,
  "product_name": "Tj1712#12号色-24码",
  "product_code": "TP00088",
  "quantity": 10,
  "billed_quantity": "0.00",
  "unit": "段",
  "size": "2.68",
  "pieces": 10,
  "description": null,
  "work_state": 0,
  "work_state_display": "生产中",
  "status": "待印染",
  "status_id": 1,
  "is_completed": false,
  "is_production_completed": false,
  "has_started": false,
  "progress_percentage": 0.0,
  "last_completed_state": "",
  "business_object_id": 2001,
  "is_sales_order_bound": false,
  "batch_advance_records": [],
  "saleitems": [],
  "fabric": "120克本白四面弹单定",
  "created_at": "2026-06-26T15:35:00+08:00",
  "updated_at": "2026-06-26T15:35:00+08:00"
}

3. 创建

POST /api/v1/printing-jobs/

Schema 注意事项

创建成功响应使用 PrintingJobCreateUpdateSerializer，不是列表/详情 serializer。因此响应只包含创建/更新字段集：id、original_id、sub_id、printing_order、external_order_id、product、quantity、unit、size、pieces、description、work_state、batch_advance_records。

创建成功响应不会返回这些列表/详情字段：merchant_id、printing_order_id、product_name、product_code、product_image_url、status、status_id、has_started、is_completed、is_production_completed、progress_percentage、last_completed_state、business_object_id、is_sales_order_bound、saleitems、fabric、created_at、updated_at。

请求体

字段	类型	必填	说明
`printing_order`	integer	是	印染订单 ID
`product`	integer	是	产品 ID
`quantity`	integer	是	数量，必须大于 0
`unit`	string	是	单位
`original_id`	integer/null	否	克隆来源任务 ID；外部同步通常由系统写入
`sub_id`	integer/null	否	外部明细子 ID
`size`	string/null	否	一段尺寸
`pieces`	integer/null	否	件数
`description`	string/null	否	备注
`work_state`	integer	否	业务进展，默认 `0`

创建接口会通过 service 自动绑定当前用户和商户，并在所属订单配置了流程时创建 BusinessObject。

4. 更新

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

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

可更新字段同创建接口。更新时不允许修改 printing_order 绑定关系；若传入不同订单，会返回 400 Bad Request。

Schema 注意事项

更新成功响应同样使用 PrintingJobCreateUpdateSerializer。字段出现规则与创建接口一致，不等同于列表/详情响应。

5. 删除

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

删除被禁用。

响应：

{
  "detail": "印染款式明细不支持删除操作"
}

状态码：405 Method Not Allowed

6. 标记完成生产

POST /api/v1/printing-jobs/mark-production-completed/

请求体：

{
  "printing_job_id": 101
}

成功响应：

{
  "message": "OK"
}

说明：

该接口只设置 is_production_completed=true
不等同于流程完成状态
不能跨商户操作

7. 推进流程

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

请求体：

{
  "parameters": {
    "temperature": "25.5",
    "operator": "张三"
  }
}

parameters 可为空；若下一流程节点定义了必填参数，则必须提供。

成功响应：

{
  "detail": "推进成功",
  "data": {
    "id": 101
  }
}

data 使用 PrintingJobDetailSerializer。

Schema 注意事项

data 是详情对象，但该接口内部直接序列化，没有传入请求上下文；因此 is_sales_order_bound 当前会返回，不受 include_sales_order_bound=false 控制。

8. 回退流程

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

成功响应：

{
  "detail": "回退成功",
  "data": {
    "id": 101
  }
}

data 使用 PrintingJobDetailSerializer。

Schema 注意事项

data 是详情对象，但该接口内部直接序列化，没有传入请求上下文；因此 is_sales_order_bound 当前会返回，不受 include_sales_order_bound=false 控制。

9. 已完成流程节点

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

查询参数：

参数	类型	必填	说明
`include_cancelled`	boolean/string	否	是否包含已撤销流程记录，默认 `false`

响应示例：

{
  "count": 1,
  "results": [
    {
      "id": 3001,
      "state_id": 1,
      "state_name": "待印染",
      "completed_at": "2026-06-26T15:35:00+08:00",
      "completed_by": "testuser",
      "completed_by_name": "测试员工",
      "is_cancelled": false,
      "cancelled_at": null
    }
  ]
}

10. 流程时间线

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

返回该任务的完整流程时间线，不包含已撤销记录。

响应示例：

{
  "count": 2,
  "results": [
    {
      "state_id": 1,
      "state_name": "待印染",
      "state_description": "",
      "order": 1,
      "status": "completed",
      "completed_at": "2026-06-26T15:35:00+08:00",
      "completed_by": "testuser",
      "completed_by_name": "测试员工"
    },
    {
      "state_id": 2,
      "state_name": "印染中",
      "state_description": "",
      "order": 2,
      "status": "in_progress",
      "completed_at": null,
      "completed_by": null,
      "completed_by_name": null
    }
  ]
}

字段补充

`work_state`

当前枚举来自 PrintingJobWorkStateEnum：

值	展示
`0`	生产中
`1`	待送货
`2`	待开单
`3`	已完结

`sub_id`

sub_id 是可空整数。外部印染 records 同步时从外部字段 SubID 写入，用于保留外部明细行的子编号。

15 KiB Raw Blame History Unescape Escape

API v1 印染任务接口说明（printing-jobs）

基础信息

接口总览

1. 列表

Schema 注意事项

查询参数

响应字段

示例

2. 详情

Schema 注意事项

路径参数

查询参数

响应字段

示例

3. 创建

Schema 注意事项

请求体

4. 更新

Schema 注意事项

5. 删除

6. 标记完成生产

7. 推进流程

Schema 注意事项

8. 回退流程

Schema 注意事项

9. 已完成流程节点

10. 流程时间线

字段补充

work_state

sub_id

15 KiB

Raw Blame History

`work_state`

`sub_id`