erpnew/docs/batch_submit_state_params.md

背景

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（即推进时的 next_pending_state）
• state_id: 同 state（便于前端直接取用）
• state_name: 节点名称
• created_by: 操作人用户 ID（可能为 null）
• created_by_username: 操作人用户名（可能为 null）
• created_by_name: 操作人员工姓名（若用户有 employee，则返回 employee.name，否则 null）
• parameters: 本次批量推进提交的参数 JSON（与推进接口 parameters 完全一致）
• created_at: 记录创建时间（ISO8601）

示例（无记录）

{
  "id": 101,
  "printing_order": 55,
  "product": 1,
  "quantity": 10,
  "unit": "米",
  "batch_advance_records": []
}

示例（有记录）

{
  "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": "张三"
      },
      "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 的批量推进接口创建审计记录。