forked from erp-dev/erp
584 lines
12 KiB
Markdown
584 lines
12 KiB
Markdown
# Stateflow 业务对象 API 文档
|
||
|
||
## 概述
|
||
|
||
业务对象（BusinessObject）是流程的实例，支持状态流转、参数管理和进度控制。
|
||
|
||
**基础路径**: `/api/v1/stateflow/business-objects/`
|
||
|
||
---
|
||
|
||
## 1. 查询下一步节点（可选带参数）
|
||
|
||
### 获取下一个待执行节点
|
||
|
||
**接口**: `GET /api/v1/stateflow/business-objects/{id}/next_pending_state/`
|
||
|
||
**描述**: 获取业务对象的下一个待执行状态节点，默认包含该状态的参数定义列表。
|
||
|
||
**查询参数**:
|
||
- `include_parameters` (可选): 是否包含参数列表，默认 `true`
|
||
- `true`: 返回参数定义列表
|
||
- `false`: 只返回状态信息
|
||
|
||
**成功响应** (200):
|
||
```json
|
||
{
|
||
"state": {
|
||
"id": 5,
|
||
"name": "质量检验",
|
||
"description": "对产品进行质量检查"
|
||
},
|
||
"order": 3,
|
||
"parameters": [
|
||
{
|
||
"id": 1,
|
||
"name": "temperature",
|
||
"display_name": "温度",
|
||
"is_required": true,
|
||
"is_image_path": false
|
||
},
|
||
{
|
||
"id": 2,
|
||
"name": "humidity",
|
||
"display_name": "湿度",
|
||
"is_required": false,
|
||
"is_image_path": false
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
**无待执行节点** (200):
|
||
```json
|
||
{
|
||
"next_state": null,
|
||
"message": "没有待执行节点（未开始或已完成）"
|
||
}
|
||
```
|
||
|
||
**示例**:
|
||
```bash
|
||
# 获取下一个节点及参数
|
||
GET /api/v1/stateflow/business-objects/123/next_pending_state/
|
||
|
||
# 只获取下一个节点，不要参数
|
||
GET /api/v1/stateflow/business-objects/123/next_pending_state/?include_parameters=false
|
||
```
|
||
|
||
---
|
||
|
||
## 2. 查询已存在的参数（可选仅包括必填）
|
||
|
||
### 2.1 获取当前状态的参数定义
|
||
|
||
**接口**: `GET /api/v1/stateflow/business-objects/{id}/current_state_parameters/`
|
||
|
||
**描述**: 获取当前状态（最后完成的状态）的参数定义列表。
|
||
|
||
**查询参数**:
|
||
- `required_only` (可选): 是否只返回必填参数，默认 `false`
|
||
- `true`: 只返回必填参数
|
||
- `false`: 返回所有参数
|
||
|
||
**成功响应** (200):
|
||
```json
|
||
{
|
||
"state": {
|
||
"id": 4,
|
||
"name": "生产加工",
|
||
"description": "进行生产加工"
|
||
},
|
||
"parameters": [
|
||
{
|
||
"id": 3,
|
||
"name": "machine_number",
|
||
"display_name": "机器编号",
|
||
"is_required": true,
|
||
"is_image_path": false
|
||
},
|
||
{
|
||
"id": 4,
|
||
"name": "operator",
|
||
"display_name": "操作员",
|
||
"is_required": true,
|
||
"is_image_path": false
|
||
}
|
||
],
|
||
"count": 2
|
||
}
|
||
```
|
||
|
||
**未完成任何状态** (200):
|
||
```json
|
||
{
|
||
"parameters": [],
|
||
"message": "尚未完成任何状态"
|
||
}
|
||
```
|
||
|
||
**示例**:
|
||
```bash
|
||
# 获取当前状态的所有参数定义
|
||
GET /api/v1/stateflow/business-objects/123/current_state_parameters/
|
||
|
||
# 只获取必填参数
|
||
GET /api/v1/stateflow/business-objects/123/current_state_parameters/?required_only=true
|
||
```
|
||
|
||
### 2.2 获取状态记录的实际参数值
|
||
|
||
**接口**: `GET /api/v1/stateflow/business-objects/{id}/state-logs/{log_id}/parameters/`
|
||
|
||
**描述**: 获取指定状态流转记录的实际参数值（用户填写的数据）。
|
||
|
||
**查询参数**:
|
||
- `key` (可选): 指定参数键，返回该参数的历史记录
|
||
- `include_cancelled` (可选): 是否包含已撤销状态的参数，默认 `false`
|
||
|
||
**成功响应 - 所有参数** (200):
|
||
```json
|
||
{
|
||
"state_log_id": 456,
|
||
"is_cancelled": false,
|
||
"count": 2,
|
||
"summary": {
|
||
"temperature": "25.5",
|
||
"humidity": "60%",
|
||
"operator": "张三"
|
||
},
|
||
"records": [
|
||
{
|
||
"id": 1,
|
||
"state_log": 456,
|
||
"parameters": {
|
||
"temperature": "25.5",
|
||
"humidity": "60%"
|
||
},
|
||
"remark": "",
|
||
"created_at": "2025-11-15T10:30:00Z",
|
||
"created_by": 1
|
||
},
|
||
{
|
||
"id": 2,
|
||
"state_log": 456,
|
||
"parameters": {
|
||
"operator": "张三"
|
||
},
|
||
"remark": "补充操作员信息",
|
||
"created_at": "2025-11-15T11:00:00Z",
|
||
"created_by": 2
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
**成功响应 - 指定参数历史** (200):
|
||
```json
|
||
{
|
||
"state_log_id": 456,
|
||
"key": "temperature",
|
||
"is_cancelled": false,
|
||
"history": [
|
||
{
|
||
"value": "25.5",
|
||
"created_at": "2025-11-15T10:30:00Z",
|
||
"created_by": 1,
|
||
"remark": ""
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
**状态记录不存在** (404):
|
||
```json
|
||
{
|
||
"success": false,
|
||
"message": "状态流转记录不存在"
|
||
}
|
||
```
|
||
|
||
**示例**:
|
||
```bash
|
||
# 获取状态记录的所有参数
|
||
GET /api/v1/stateflow/business-objects/123/state-logs/456/parameters/
|
||
|
||
# 获取特定参数的历史
|
||
GET /api/v1/stateflow/business-objects/123/state-logs/456/parameters/?key=temperature
|
||
|
||
# 包含已撤销状态的参数
|
||
GET /api/v1/stateflow/business-objects/123/state-logs/456/parameters/?include_cancelled=true
|
||
```
|
||
|
||
---
|
||
|
||
## 3. 推进到下一步（校验必填参数）
|
||
|
||
**接口**: `POST /api/v1/stateflow/business-objects/{id}/advance/`
|
||
|
||
**描述**: 推进业务对象到下一个状态，自动校验必填参数。
|
||
|
||
**请求体**:
|
||
```json
|
||
{
|
||
"parameters": {
|
||
"temperature": "25.5",
|
||
"humidity": "60%",
|
||
"operator": "张三"
|
||
}
|
||
}
|
||
```
|
||
|
||
**参数说明**:
|
||
- `parameters` (可选): 参数字典
|
||
- 如果下一个状态有必填参数，则必须提供所有必填参数
|
||
- 可以包含可选参数
|
||
- 参数值以字符串形式存储
|
||
|
||
**成功响应** (200):
|
||
```json
|
||
{
|
||
"success": true,
|
||
"message": "已推进到状态: 质量检验",
|
||
"state_log": {
|
||
"id": 456,
|
||
"state": {
|
||
"id": 5,
|
||
"name": "质量检验"
|
||
},
|
||
"completed_at": "2025-11-15T10:30:00Z",
|
||
"completed_by": {
|
||
"id": 1,
|
||
"username": "zhangsan"
|
||
},
|
||
"is_cancelled": false,
|
||
"parameters_summary": {
|
||
"temperature": "25.5",
|
||
"humidity": "60%"
|
||
}
|
||
},
|
||
"business_object": {
|
||
"id": 123,
|
||
"name": "订单-001",
|
||
"process": {...},
|
||
"overall_status": "in_progress",
|
||
"current_state": {...}
|
||
}
|
||
}
|
||
```
|
||
|
||
**校验失败 - 缺少必填参数** (400):
|
||
```json
|
||
{
|
||
"success": false,
|
||
"message": "缺少必填参数: temperature, operator"
|
||
}
|
||
```
|
||
|
||
**其他失败情况** (400):
|
||
```json
|
||
{
|
||
"success": false,
|
||
"message": "已经完成所有状态"
|
||
}
|
||
```
|
||
|
||
**示例**:
|
||
```bash
|
||
# 推进到下一状态（带参数）
|
||
curl -X POST /api/v1/stateflow/business-objects/123/advance/ \
|
||
-H "Content-Type: application/json" \
|
||
-d '{"parameters": {"temperature": "25.5", "humidity": "60%"}}'
|
||
|
||
# 推进到下一状态（无参数）
|
||
curl -X POST /api/v1/stateflow/business-objects/123/advance/ \
|
||
-H "Content-Type: application/json" \
|
||
-d '{}'
|
||
```
|
||
|
||
---
|
||
|
||
## 4. 回退
|
||
|
||
**接口**: `POST /api/v1/stateflow/business-objects/{id}/step_back/`
|
||
|
||
**描述**: 回退一步，撤销最后一次完成的状态（标记为已撤销，不删除记录）。
|
||
|
||
**请求体**: 无需请求体
|
||
|
||
**成功响应** (200):
|
||
```json
|
||
{
|
||
"success": true,
|
||
"message": "已回退到状态: 生产加工",
|
||
"business_object": {
|
||
"id": 123,
|
||
"name": "订单-001",
|
||
"process": {...},
|
||
"overall_status": "in_progress",
|
||
"current_state": {...}
|
||
}
|
||
}
|
||
```
|
||
|
||
**失败响应** (400):
|
||
```json
|
||
{
|
||
"success": false,
|
||
"message": "没有可回退的状态"
|
||
}
|
||
```
|
||
|
||
**示例**:
|
||
```bash
|
||
curl -X POST /api/v1/stateflow/business-objects/123/step_back/
|
||
```
|
||
|
||
---
|
||
|
||
## 5. 针对已完成的状态节点添加新的参数集
|
||
|
||
**接口**: `POST /api/v1/stateflow/business-objects/{id}/state-logs/{log_id}/add-parameters/`
|
||
|
||
**描述**: 为已完成的状态流转记录补充参数（追加新的参数记录）。
|
||
|
||
**请求体**:
|
||
```json
|
||
{
|
||
"parameters": {
|
||
"additional_note": "发现轻微瑕疵",
|
||
"inspector": "李四"
|
||
},
|
||
"remark": "质检员补充信息"
|
||
}
|
||
```
|
||
|
||
**参数说明**:
|
||
- `parameters` (必填): 参数字典，不能为空
|
||
- `remark` (可选): 备注说明
|
||
|
||
**成功响应** (200):
|
||
```json
|
||
{
|
||
"success": true,
|
||
"parameter_record": {
|
||
"id": 789,
|
||
"state_log": 456,
|
||
"parameters": {
|
||
"additional_note": "发现轻微瑕疵",
|
||
"inspector": "李四"
|
||
},
|
||
"remark": "质检员补充信息",
|
||
"created_at": "2025-11-15T14:30:00Z",
|
||
"created_by": 2
|
||
}
|
||
}
|
||
```
|
||
|
||
**失败响应 - 状态记录不存在** (404):
|
||
```json
|
||
{
|
||
"success": false,
|
||
"message": "状态流转记录不存在"
|
||
}
|
||
```
|
||
|
||
**失败响应 - 参数为空** (400):
|
||
```json
|
||
{
|
||
"success": false,
|
||
"message": "参数不能为空"
|
||
}
|
||
```
|
||
|
||
**示例**:
|
||
```bash
|
||
curl -X POST /api/v1/stateflow/business-objects/123/state-logs/456/add-parameters/ \
|
||
-H "Content-Type: application/json" \
|
||
-d '{
|
||
"parameters": {
|
||
"additional_note": "发现轻微瑕疵",
|
||
"inspector": "李四"
|
||
},
|
||
"remark": "质检员补充信息"
|
||
}'
|
||
```
|
||
|
||
---
|
||
|
||
## 6. 其他相关接口
|
||
|
||
### 6.1 获取状态时间线
|
||
|
||
**接口**: `GET /api/v1/stateflow/business-objects/{id}/timeline/`
|
||
|
||
**描述**: 获取业务对象的完整状态时间线。
|
||
|
||
**成功响应** (200):
|
||
```json
|
||
[
|
||
{
|
||
"state": {
|
||
"id": 1,
|
||
"name": "接单"
|
||
},
|
||
"status": "completed",
|
||
"order": 1,
|
||
"completed_at": "2025-11-15T09:00:00Z",
|
||
"completed_by": "zhangsan",
|
||
"cancelled_at": null,
|
||
"is_cancelled": false
|
||
},
|
||
{
|
||
"state": {
|
||
"id": 2,
|
||
"name": "生产加工"
|
||
},
|
||
"status": "completed",
|
||
"order": 2,
|
||
"completed_at": "2025-11-15T10:00:00Z",
|
||
"completed_by": "lisi",
|
||
"cancelled_at": null,
|
||
"is_cancelled": false
|
||
},
|
||
{
|
||
"state": {
|
||
"id": 3,
|
||
"name": "质量检验"
|
||
},
|
||
"status": "pending",
|
||
"order": 3,
|
||
"completed_at": null,
|
||
"completed_by": null,
|
||
"cancelled_at": null,
|
||
"is_cancelled": false
|
||
}
|
||
]
|
||
```
|
||
|
||
### 6.2 获取所有待执行节点
|
||
|
||
**接口**: `GET /api/v1/stateflow/business-objects/{id}/pending_states/`
|
||
|
||
**描述**: 获取所有待执行的状态节点列表（不包含参数）。
|
||
|
||
**成功响应** (200):
|
||
```json
|
||
{
|
||
"count": 2,
|
||
"pending_states": [
|
||
{
|
||
"state": {
|
||
"id": 3,
|
||
"name": "质量检验"
|
||
},
|
||
"order": 3
|
||
},
|
||
{
|
||
"state": {
|
||
"id": 4,
|
||
"name": "打包发货"
|
||
},
|
||
"order": 4
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
### 6.3 重置进度
|
||
|
||
**接口**: `POST /api/v1/stateflow/business-objects/{id}/reset/`
|
||
|
||
**描述**: 重置业务对象的进度（删除所有状态记录）。
|
||
|
||
**成功响应** (200):
|
||
```json
|
||
{
|
||
"success": true,
|
||
"message": "进度已重置",
|
||
"business_object": {...}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 完整性检查清单
|
||
|
||
根据您的需求，所有接口都已齐全：
|
||
|
||
- ✅ **查询下一步节点（可选带参数）**: `GET next_pending_state/` (支持 `include_parameters` 参数)
|
||
- ✅ **查询已存在的参数（可选仅包括必填）**:
|
||
- `GET current_state_parameters/` (支持 `required_only` 参数) - 参数定义
|
||
- `GET state-logs/{log_id}/parameters/` - 实际参数值
|
||
- ✅ **回退**: `POST step_back/`
|
||
- ✅ **推进到下一步（校验必填参数）**: `POST advance/` (自动校验必填参数)
|
||
- ✅ **针对已完成的状态节点添加新的参数集**: `POST state-logs/{log_id}/add-parameters/`
|
||
|
||
---
|
||
|
||
## 典型使用流程
|
||
|
||
### 场景 1: 推进到下一状态
|
||
|
||
```bash
|
||
# 1. 查询下一个待执行节点及参数要求
|
||
GET /api/v1/stateflow/business-objects/123/next_pending_state/
|
||
|
||
# 响应显示需要 temperature (必填) 和 humidity (可选)
|
||
|
||
# 2. 推进到下一状态（提供必填参数）
|
||
POST /api/v1/stateflow/business-objects/123/advance/
|
||
{
|
||
"parameters": {
|
||
"temperature": "25.5",
|
||
"humidity": "60%"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 场景 2: 补充参数
|
||
|
||
```bash
|
||
# 1. 从时间线获取已完成状态的 state_log_id
|
||
GET /api/v1/stateflow/business-objects/123/timeline/
|
||
|
||
# 2. 为指定状态记录补充参数
|
||
POST /api/v1/stateflow/business-objects/123/state-logs/456/add-parameters/
|
||
{
|
||
"parameters": {
|
||
"inspector": "李四",
|
||
"note": "补充检验员信息"
|
||
},
|
||
"remark": "质检后补充"
|
||
}
|
||
```
|
||
|
||
### 场景 3: 查询参数
|
||
|
||
```bash
|
||
# 1. 查询当前状态的必填参数定义
|
||
GET /api/v1/stateflow/business-objects/123/current_state_parameters/?required_only=true
|
||
|
||
# 2. 查询某个状态记录的实际参数值
|
||
GET /api/v1/stateflow/business-objects/123/state-logs/456/parameters/
|
||
|
||
# 3. 查询某个参数的修改历史
|
||
GET /api/v1/stateflow/business-objects/123/state-logs/456/parameters/?key=temperature
|
||
```
|
||
|
||
---
|
||
|
||
## 重要说明
|
||
|
||
1. **参数存储**: 所有参数值以字符串形式存储在 JSONField 中，支持灵活的数据结构
|
||
2. **参数校验**: 仅校验必填参数是否提供，不校验参数值的格式或类型
|
||
3. **撤销状态**: 回退操作不删除记录，而是标记为已撤销（`is_cancelled=True`）
|
||
4. **参数可见性**: 默认情况下，已撤销状态的参数不会返回，需要显式传递 `include_cancelled=true`
|
||
5. **参数追加**: 可以多次为同一个状态记录添加参数，所有记录都会保留
|
||
6. **参数历史**: 支持查询单个参数的修改历史，按时间顺序返回
|
||
|
||
---
|
||
|
||
**文档版本**: 2025-11-15
|
||
**测试覆盖**: 55 个测试用例全部通过
|