# 批量补充工艺参数 API

## 概述

为多个 `PrintingJob` 的已完成状态流转记录批量补充工艺参数。

- **端点**: `POST /api/v2/printing-jobs/batch-add-parameters/`
- **认证**: 需要登录
- **权限**: 印染工厂用户

## 与批量推进的区别

| 维度 | batch-advance | batch-add-parameters |
|------|---------------|----------------------|
| **目的** | 推进流程状态 | 补充已完成状态的参数 |
| **前置条件** | jobs 处于同一待推进状态 | jobs 已完成指定状态 |
| **核心操作** | `advance_to_next_state()` | `add_parameters_to_state_log()` |
| **审计记录** | `only_parameters=False` | `only_parameters=True` |

## 请求

### 请求体

```json
{
  "printing_job_ids": [101, 102, 103],
  "state_id": 7,
  "parameters": {
    "temperature": "26.0",
    "operator": "李四",
    "remark_field": "补测数据"
  },
  "remark": "批量补充参数备注"
}
```

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `printing_job_ids` | array[int] | 是 | 印染明细ID列表 |
| `state_id` | int | 是 | 目标流程节点ID（State.id） |
| `parameters` | object | 是 | 要补充的工艺参数（不能为空） |
| `remark` | string | 否 | 备注说明 |

### 请求示例

```bash
curl -X POST "http://localhost:8000/api/v2/printing-jobs/batch-add-parameters/" \
  -H "Authorization: Token <your-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "printing_job_ids": [101, 102, 103],
    "state_id": 7,
    "parameters": {"temperature": "26.0", "operator": "李四"},
    "remark": "补测数据"
  }'
```

## 响应

### 成功响应 (200 OK)

```json
{
  "detail": "批量补充参数成功",
  "batch_record_id": 15,
  "printing_order_id": 55,
  "printing_job_ids": [101, 102, 103],
  "state_id": 7,
  "state_name": "染色",
  "parameters": {
    "temperature": "26.0",
    "operator": "李四"
  },
  "affected_count": 3
}
```

### 响应字段说明

| 字段 | 类型 | 说明 |
|------|------|------|
| `detail` | string | 操作结果消息 |
| `batch_record_id` | int | 批量操作记录ID |
| `printing_order_id` | int | 印染订单ID |
| `printing_job_ids` | array[int] | 受影响的印染明细ID列表 |
| `state_id` | int | 目标流程节点ID |
| `state_name` | string | 流程节点名称 |
| `parameters` | object | 补充的工艺参数 |
| `affected_count` | int | 受影响的明细数量 |

### 错误响应

#### 参数为空 (400 Bad Request)

```json
{
  "detail": "参数不能为空"
}
```

#### Job 不存在 (400 Bad Request)

```json
{
  "detail": "以下 PrintingJob 不存在: [999]",
  "missing_jobs": [999]
}
```

#### Jobs 属于不同订单 (400 Bad Request)

```json
{
  "detail": "所有 PrintingJob 必须属于同一个 PrintingOrder"
}
```

#### Job 没有流程实例 (400 Bad Request)

```json
{
  "detail": "以下 PrintingJob 没有流程实例 (business_object): [101]",
  "missing_business_object": [101]
}
```

#### Job 没有对应状态记录 (400 Bad Request)

```json
{
  "detail": "以下 PrintingJob 没有对应 state_id=7 的状态流转记录（或已撤销）: [103]",
  "missing_state_log": [103]
}
```

#### State 不存在 (400 Bad Request)

```json
{
  "detail": "State ID 999 不存在"
}
```

#### 未认证 (401 Unauthorized)

```json
{
  "detail": "Authentication credentials were not provided."
}
```

## 验证规则

| 规则 | 说明 |
|------|------|
| ① 所有 job 必须存在 | 返回 `missing_jobs` |
| ② 所有 job 必须属于同一个 `printing_order` | 与 batch_advance 一致 |
| ③ 所有 job 必须有 `business_object` | 返回 `missing_business_object` |
| ④ 所有 job 必须有对应 `state_id` 的未撤销状态记录 | 返回 `missing_state_log` |
| ⑤ `parameters` 不能为空 | 与单条 add-parameters 一致 |

## 事务策略

- **全成功/全失败**：任意一个 job 验证失败 → 整体失败，不写入任何数据
- 使用 `transaction.atomic()` 包裹

## 审计记录

操作成功后会创建 `PrintingJobBatchAdvanceRecord` 记录：

| 字段 | 值 |
|------|-----|
| `printing_order` | 印染订单 |
| `state` | 操作的流程节点 |
| `parameters` | 补充的参数 |
| `printing_jobs` | 涉及的明细 |
| `created_by` | 操作人 |
| `only_parameters` | **`True`** |

可通过 `GET /api/v2/printing-orders/{id}/batch-advance-records/` 查询所有批量操作记录。

## 前端使用示例

```javascript
// 批量补充参数
async function batchAddParameters(printingJobIds, stateId, parameters, remark = '') {
  const response = await fetch('/api/v2/printing-jobs/batch-add-parameters/', {
    method: 'POST',
    headers: {
      'Authorization': `Token ${token}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      printing_job_ids: printingJobIds,
      state_id: stateId,
      parameters: parameters,
      remark: remark
    })
  });
  
  if (!response.ok) {
    const error = await response.json();
    throw new Error(error.detail);
  }
  
  return await response.json();
}

// 使用示例
try {
  const result = await batchAddParameters(
    [101, 102, 103],
    7,
    { temperature: '26.0', operator: '李四' },
    '补测数据'
  );
  console.log(`成功补充 ${result.affected_count} 条明细的参数`);
} catch (error) {
  console.error('补充参数失败:', error.message);
}
```

## 相关文档

- [批量推进 API](./api_v2_advance_printing_jobs_api.md)
- [批量操作记录查询](./api_v2_printing_order_batch_advance_records.md)
- [单条补充参数 API](./batch_submit_state_params.md)

## 相关模型

- `printing.PrintingJobBatchAdvanceRecord` - 批量操作记录（`only_parameters=True`）
- `printing.PrintingJob` - 印染明细
- `stateflow.StateFlowRecord` - 状态流转记录
- `stateflow.StateLogParameterRecord` - 参数记录