### 文档说明
本文档描述 `api_v2` 中 **PrintingJob 批量推进流程状态**的两个接口（preview + submit），用于前端生成批量表单与提交批量推进。

### 背景与术语
- **PrintingJob**：概念上等同于“订单明细对象”，归属一个 `PrintingOrder`。
- **Stateflow**：PrintingJob 通过 `business_object`（`stateflow.BusinessObject`）承载流程实例；推进逻辑复用 `stateflow.services.advance_to_next_state(...)`。
- **批量推进**：对多个 PrintingJob（要求同一订单、同一待执行节点）使用同一份工艺参数推进一个节点。

### 权限与鉴权
- **鉴权**：需要登录（`IsAuthenticated`），使用系统统一 JWT 认证。
- **业务权限**：需要印染工厂身份（`IsPrintingFactory`），即 `request.user.employee.merchant.type == FACTORY`。

### 路由与代码位置
- **Base**：`/api/v2/`
- **实现文件**：`api_v2/views/printing.py`
- **路由定义**：`api_v2/urls.py`

### 统一校验规则（preview 与 submit 共用）
批量推进（或预览）必须同时满足：
- **ID 存在**：`printing_job_ids` 全部存在，否则 400。
- **同一订单**：所有 job 必须属于同一个 `printing_order`，否则 400。
- **必须绑定流程实例**：每个 job 必须有 `business_object`，否则 400。
- **同一待执行节点**：所有 job 的 `next_pending_state` 必须一致，否则 400。
- **可推进**：任一 job 的 `next_pending_state` 为 `None`（流程已完成或无节点）则 400。

> 备注：当前 **不做 preview→submit 竞态处理**（例如 preview 通过后，期间有人推进了其中部分 job）。submit 会重新校验；如需更好的用户体验，后续可引入 snapshot token / 幂等键。

---

## 批量推进预览（用于生成批量表单）
### Endpoint
- **POST** `api/v2/printing-jobs/batch-advance/preview/`

### Request Body
```json
{
  "printing_job_ids": [101, 102, 103]
}
```

### Response（200）
返回下一待执行节点（统一）及其工艺参数定义：
```json
{
  "printing_order_id": 55,
  "printing_job_ids": [101, 102, 103],
  "next_state": {
    "id": 7,
    "name": "染色",
    "description": "染色工序",
    "order": 0,
    "parameters": [
      {
        "id": 12,
        "key": "temperature",
        "value": "",
        "attachment": null,
        "attachment_url": null,
        "description": "温度（必填）",
        "is_required": true,
        "is_image_path": false
      }
    ]
  }
}
```

### 典型错误（400）
返回 `{"detail": "<原因>"}` 或字段级错误，例如：
- 不同订单：`所选明细不属于同一个 printing_order，无法批量推进`
- 缺 business_object：`以下 printing_job 未关联流程实例（business_object），无法推进: ...`
- next_state 不一致：`所选明细当前待执行节点不一致，无法批量推进...`
- 已完成/无节点：`没有待执行节点（流程已完成或无节点）`

---

## 批量推进提交（全成功/全失败）
### Endpoint
- **POST** `api/v2/printing-jobs/batch-advance/`

### 语义（重要）
- **事务全成功/全失败**：接口使用数据库事务包裹：
  - 创建批量推进记录（审计表）
  - 逐个调用 `stateflow.services.advance_to_next_state(...)` 推进每个 job 的 `business_object`
  - 任意一个 job 推进失败：**整体回滚**（不会产生任何 stateflow 日志，也不会产生批量记录）

### Request Body
```json
{
  "printing_job_ids": [101, 102, 103],
  "parameters": {
    "temperature": "25.5",
    "operator": "张三"
  }
}
```
说明：
- `parameters` 会作为 `**kwargs` 传入 `stateflow.services.advance_to_next_state(...)`。
- 若下一节点存在必填参数（`is_required=true`），则必须提供对应 key，否则返回 400（错误信息形如 `缺失必填参数: temperature`）。

### Response（200）
```json
{
  "detail": "已完成状态: 染色",
  "batch_id": 9,
  "printing_order_id": 55,
  "printing_job_ids": [101, 102, 103],
  "jobs": [
    {
      "id": 101,
      "printing_order": 55,
      "product": { "id": 1, "...": "..." },
      "work_state": 0,
      "quantity": 10,
      "width": "150cm",
      "fabric": "棉",
      "unit": "米",
      "size": null,
      "pieces": null,
      "description": null,
      "business_object_id": 888,
      "created_at": "2025-12-12T10:00:00+08:00",
      "updated_at": "2025-12-12T10:01:00+08:00",
      "billed_quantity": "0.00"
    }
  ]
}
```
说明：
- `jobs` 使用 `PrintingJobV2Serializer`：其中 `product` 为嵌套对象（不是纯 ID）。

### 典型错误（400）
- 参数缺失：`{"detail": "缺失必填参数: temperature"}`
- 不满足一致性校验：同 preview 的错误列表。

---

## 批量推进审计表：PrintingJobBatchAdvanceRecord
### 模型
`printing.models.PrintingJobBatchAdvanceRecord`

### 字段（核心）
- `created_at` / `updated_at`：来自 `ModelBase`
- `created_by`：操作人（可空，删除用户后保留记录）
- `printing_order`：所属主订单
- `state`：本次被“完成”的流程节点（推进时的 next_pending_state）
- `parameters`：本次批量推进提交的参数（JSON）
- `printing_jobs`：本次批量推进涉及的明细集合（ManyToMany）

### 迁移
- `printing/migrations/0024_printingjobbatchadvancerecord.py`

---

## 前端联调建议
- 先调用 preview 获取 `next_state.parameters` 生成批量表单（必填项根据 `is_required`）。
- 表单提交调用 submit；如返回 400，提示 `detail` 并建议用户刷新列表后重试。
- 当前未实现竞态 token/幂等键；如需要防重复提交，建议后续加 `Idempotency-Key`（前端生成 UUID，后端在批量记录表上做去重）。