erpnew/docs/api_v2_batch_add_parameters.md

批量补充工艺参数 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

请求

请求体

{
  "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	否	备注说明

请求示例

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)

{
  "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)

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

Job 不存在 (400 Bad Request)

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

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

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

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

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

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

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

State 不存在 (400 Bad Request)

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

未认证 (401 Unauthorized)

{
  "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/ 查询所有批量操作记录。

前端使用示例

// 批量补充参数
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

相关模型

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