# 获取印染订单批量推进记录 API

## 概述

根据印染订单ID查询该订单下所有的批量推进审计记录。

- **端点**: `GET /api/v2/printing-orders/{printing_order_id}/batch-advance-records/`
- **认证**: 需要登录
- **权限**: 任意已认证用户

## 背景

`PrintingJob`（印染订单明细）在批量推进流程时，会产生 `PrintingJobBatchAdvanceRecord` 审计记录。此 API 用于查询某个印染订单下的所有批量推进历史。

## 请求

### 路径参数

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `printing_order_id` | int | 是 | 印染订单ID |

### 请求示例

```bash
curl -X GET "http://localhost:8000/api/v2/printing-orders/55/batch-advance-records/" \
  -H "Authorization: Token <your-token>"
```

## 响应

### 成功响应 (200 OK)

```json
{
  "printing_order_id": 55,
  "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": "张三"
      },
      "printing_job_ids": [101, 102, 103],
      "printing_job_count": 3,
      "created_at": "2025-12-14T10:00:00+08:00"
    }
  ],
  "total_count": 1
}
```

### 响应字段说明

| 字段 | 类型 | 说明 |
|------|------|------|
| `printing_order_id` | int | 印染订单ID |
| `records` | array | 批量推进记录列表（按创建时间倒序） |
| `total_count` | int | 记录总数 |

### records 对象结构

| 字段 | 类型 | 说明 |
|------|------|------|
| `id` | int | 批量推进记录ID |
| `printing_order` | int | 印染订单ID |
| `state` | int | 完成的流程节点ID |
| `state_id` | int | 同 `state`（便于前端直接取用） |
| `state_name` | string | 流程节点名称 |
| `created_by` | int \| null | 操作人用户ID |
| `created_by_username` | string \| null | 操作人用户名 |
| `created_by_name` | string \| null | 操作人员工姓名 |
| `parameters` | object | 批量推进时提交的工艺参数 |
| `printing_job_ids` | array[int] | 涉及的印染明细ID列表 |
| `printing_job_count` | int | 涉及的印染明细数量 |
| `created_at` | string | 创建时间（ISO8601） |

### 无记录时的响应

```json
{
  "printing_order_id": 100,
  "records": [],
  "total_count": 0
}
```

### 错误响应

#### 订单不存在 (404 Not Found)

```json
{
  "error": "未找到 ID 为 999 的印染订单"
}
```

#### 未认证 (401 Unauthorized)

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

## 前端使用示例

```javascript
// 获取印染订单的批量推进记录
async function getBatchAdvanceRecords(printingOrderId) {
  const response = await fetch(
    `/api/v2/printing-orders/${printingOrderId}/batch-advance-records/`,
    { headers: { 'Authorization': `Token ${token}` } }
  );
  const data = await response.json();
  
  // 显示每次批量推进的参数和涉及的明细
  data.records.forEach(record => {
    console.log(`${record.state_name}: ${record.printing_job_count} 条明细`);
    console.log('参数:', record.parameters);
  });
  
  return data;
}
```

## 相关文档

- [批量推进记录字段说明](./batch_submit_state_params.md) - `api_v1` 中的 `batch_advance_records` 字段说明
- 批量推进接口: `POST /api/v2/printing-jobs/batch-advance/`

## 相关模型

- `printing.PrintingJobBatchAdvanceRecord` - 批量推进记录
- `printing.PrintingOrder` - 印染订单
- `printing.PrintingJob` - 印染明细
- `stateflow.State` - 流程节点

