feat: added new api for query batch_advance_records

docs/api_v2_printing_order_batch_advance_records.md

@@ -0,0 +1,145 @@
+# 获取印染订单批量推进记录 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` - 流程节点
+