forked from erp-dev/erp
82 lines
3.1 KiB
Markdown
82 lines
3.1 KiB
Markdown
### 背景
|
||
`PrintingJob` 在业务上等同于“印染订单明细”。当使用批量推进接口（例如 `api_v2` 的批量推进）对多个明细用同一份参数推进流程时，需要在后端保留一条**批量推进审计记录**，并在 `api_v1` 的 PrintingJob 相关接口返回该记录，方便前端展示“这条明细曾经参与过哪些批量推进、当时提交了哪些工艺参数”。
|
||
|
||
### 变更点概述（api_v1）
|
||
在 `api_v1` 的 PrintingJob 相关序列化输出中新增字段：
|
||
- **`batch_advance_records`**：始终存在（key 永远输出）
|
||
- 若该 job 没有批量推进记录：返回 `[]`
|
||
- 若存在记录：返回记录数组（按创建时间倒序）
|
||
|
||
> 该字段是新增字段，不会影响老客户端；对前端而言可以直接依赖该 key 的存在性，无需做 “undefined/null” 兼容。
|
||
|
||
### 返回字段结构：batch_advance_records
|
||
每条记录（PrintingJobBatchAdvanceRecord）包含：
|
||
- `id`: 批量操作记录 ID
|
||
- `printing_order`: 主订单 ID
|
||
- `state`: 本次批量操作的流程节点 ID
|
||
- `state_id`: 同 `state`（便于前端直接取用）
|
||
- `state_name`: 节点名称
|
||
- `created_by`: 操作人用户 ID（可能为 null）
|
||
- `created_by_username`: 操作人用户名（可能为 null）
|
||
- `created_by_name`: 操作人员工姓名（若用户有 employee，则返回 employee.name，否则 null）
|
||
- `parameters`: 本次批量操作提交的参数 JSON
|
||
- `only_parameters`: 操作类型标识
|
||
- `false`（默认）：批量推进状态
|
||
- `true`：仅批量补充工艺参数（不推进状态）
|
||
- `created_at`: 记录创建时间（ISO8601）
|
||
|
||
### 示例（无记录）
|
||
```json
|
||
{
|
||
"id": 101,
|
||
"printing_order": 55,
|
||
"product": 1,
|
||
"quantity": 10,
|
||
"unit": "米",
|
||
"batch_advance_records": []
|
||
}
|
||
```
|
||
|
||
### 示例（有记录）
|
||
```json
|
||
{
|
||
"id": 101,
|
||
"printing_order": 55,
|
||
"product": 1,
|
||
"quantity": 10,
|
||
"unit": "米",
|
||
"batch_advance_records": [
|
||
{
|
||
"id": 9,
|
||
"printing_order": 55,
|
||
"state": 7,
|
||
"state_id": 7,
|
||
"state_name": "染色",
|
||
"created_by": 1001,
|
||
"created_by_username": "factory_user",
|
||
"created_by_name": "张三",
|
||
"parameters": {
|
||
"temperature": "25.5",
|
||
"operator": "张三"
|
||
},
|
||
"only_parameters": false,
|
||
"created_at": "2025-12-14T10:00:00+08:00"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
### 相关实现位置
|
||
- **serializer 增字段**：`api_v1/views/printing/serializers.py`
|
||
- `PrintingJobListSerializer.batch_advance_records`
|
||
- `PrintingJobDetailSerializer.batch_advance_records`
|
||
- `PrintingJobCreateUpdateSerializer.batch_advance_records`
|
||
- `PrintingJobBatchAdvanceRecordSerializer`
|
||
- **避免 N+1**：`api_v1/views/printing/views.py`（`PrintingJobViewSet.get_queryset()` 预取 `batch_advance_records`）
|
||
|
||
### 注意事项
|
||
- 记录中的 `parameters` 为**批量提交时的原始参数**，不会自动与 stateflow 的参数历史做合并；若需要查看某次推进在 stateflow 中落地的参数记录，请以 stateflow 日志为准。
|
||
- 当前文档只描述 `api_v1` 输出字段；批量推进行为本身由 `api_v2` 的批量推进接口创建审计记录。
|
||
|
||
|