### 背景 `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` 的批量推进接口创建审计记录。