forked from erp-dev/erp
484 lines
15 KiB
Markdown
484 lines
15 KiB
Markdown
# 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 | 更新时间 |
|
||
|
||
### 示例
|
||
|
||
```bash
|
||
curl "http://localhost:8100/api/v1/printing-jobs/?external_order_id=KD20410611&limit=50" \
|
||
-H "Authorization: Bearer <token>"
|
||
```
|
||
|
||
响应示例：
|
||
|
||
```json
|
||
{
|
||
"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 | 更新时间 |
|
||
|
||
### 示例
|
||
|
||
```bash
|
||
curl "http://localhost:8100/api/v1/printing-jobs/101/" \
|
||
-H "Authorization: Bearer <token>"
|
||
```
|
||
|
||
响应示例：
|
||
|
||
```json
|
||
{
|
||
"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}/`
|
||
|
||
删除被禁用。
|
||
|
||
响应：
|
||
|
||
```json
|
||
{
|
||
"detail": "印染款式明细不支持删除操作"
|
||
}
|
||
```
|
||
|
||
状态码：`405 Method Not Allowed`
|
||
|
||
## 6. 标记完成生产
|
||
|
||
`POST /api/v1/printing-jobs/mark-production-completed/`
|
||
|
||
请求体：
|
||
|
||
```json
|
||
{
|
||
"printing_job_id": 101
|
||
}
|
||
```
|
||
|
||
成功响应：
|
||
|
||
```json
|
||
{
|
||
"message": "OK"
|
||
}
|
||
```
|
||
|
||
说明：
|
||
|
||
- 该接口只设置 `is_production_completed=true`
|
||
- 不等同于流程完成状态
|
||
- 不能跨商户操作
|
||
|
||
## 7. 推进流程
|
||
|
||
`POST /api/v1/printing-jobs/{id}/advance-to-next-state/`
|
||
|
||
请求体：
|
||
|
||
```json
|
||
{
|
||
"parameters": {
|
||
"temperature": "25.5",
|
||
"operator": "张三"
|
||
}
|
||
}
|
||
```
|
||
|
||
`parameters` 可为空；若下一流程节点定义了必填参数，则必须提供。
|
||
|
||
成功响应：
|
||
|
||
```json
|
||
{
|
||
"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/`
|
||
|
||
成功响应：
|
||
|
||
```json
|
||
{
|
||
"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` |
|
||
|
||
响应示例：
|
||
|
||
```json
|
||
{
|
||
"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/`
|
||
|
||
返回该任务的完整流程时间线，不包含已撤销记录。
|
||
|
||
响应示例：
|
||
|
||
```json
|
||
{
|
||
"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` 写入，用于保留外部明细行的子编号。
|