feat: batch add parameters

2026-01-07 16:33:33 +08:00
parent 5b07332015
commit beaa93c3cb
9 changed files with 722 additions and 15 deletions
--- a/docs/api_v2_batch_add_parameters.md
+++ b/docs/api_v2_batch_add_parameters.md
@@ -0,0 +1,235 @@
+# 批量补充工艺参数 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` - 参数记录
+
--- a/docs/batch_submit_state_params.md
+++ b/docs/batch_submit_state_params.md
@@ -11,15 +11,18 @@

 ### 返回字段结构：batch_advance_records
 每条记录（PrintingJobBatchAdvanceRecord）包含：
- `id`: 批量推进记录 ID
+- `id`: 批量操作记录 ID
 - `printing_order`: 主订单 ID
- `state`: 本次批量推进“完成”的流程节点 ID（即推进时的 next_pending_state）
+- `state`: 本次批量操作的流程节点 ID
 - `state_id`: 同 `state`（便于前端直接取用）
 - `state_name`: 节点名称
 - `created_by`: 操作人用户 ID（可能为 null）
 - `created_by_username`: 操作人用户名（可能为 null）
 - `created_by_name`: 操作人员工姓名（若用户有 employee，则返回 employee.name，否则 null）
- `parameters`: 本次批量推进提交的参数 JSON（与推进接口 `parameters` 完全一致）
+- `parameters`: 本次批量操作提交的参数 JSON
+- `only_parameters`: 操作类型标识
+  - `false`（默认）：批量推进状态
+  - `true`：仅批量补充工艺参数（不推进状态）
 - `created_at`: 记录创建时间（ISO8601）

 ### 示例（无记录）
@@ -56,6 +59,7 @@
        "temperature": "25.5",
        "operator": "张三"
      },
+      "only_parameters": false,
      "created_at": "2025-12-14T10:00:00+08:00"
    }
  ]