forked from erp-dev/erp
236 lines
5.7 KiB
Markdown
236 lines
5.7 KiB
Markdown
# 批量补充工艺参数 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` - 参数记录
|
||
|