forked from erp-dev/erp
178 lines
4.1 KiB
Markdown
178 lines
4.1 KiB
Markdown
# 新增功能：获取业务对象流程节点接口
|
|
|
|
## 概述
|
|
|
|
为 Stateflow 模块新增了获取业务对象所属流程的所有状态节点的功能。
|
|
|
|
## 变更内容
|
|
|
|
### 1. Services 层 (`stateflow/services.py`)
|
|
|
|
新增函数 `get_process_nodes(business_object)`:
|
|
|
|
```python
|
|
def get_process_nodes(business_object: 'models.BusinessObject') -> List[dict]:
|
|
"""
|
|
获取业务对象所属流程的所有状态节点列表
|
|
|
|
参数:
|
|
business_object: BusinessObject 实例
|
|
|
|
返回:
|
|
节点列表，每个元素包含：
|
|
{
|
|
'id': ProcessNode ID,
|
|
'state': State对象,
|
|
'state_id': State ID,
|
|
'state_name': State 名称,
|
|
'order': 节点顺序号
|
|
}
|
|
"""
|
|
```
|
|
|
|
**用途**: 获取完整的流程节点列表，包含节点顺序和状态信息。
|
|
|
|
### 2. API 层 (`api_v1/views/stateflow/business_object.py`)
|
|
|
|
新增 API 端点:
|
|
|
|
- **URL**: `GET /api/v1/stateflow/business-objects/{id}/process-nodes/`
|
|
- **描述**: 获取指定业务对象所属流程的所有状态节点
|
|
- **响应格式**:
|
|
|
|
```json
|
|
{
|
|
"count": 3,
|
|
"nodes": [
|
|
{
|
|
"id": 1,
|
|
"state_id": 10,
|
|
"state_name": "质检",
|
|
"order": 0
|
|
},
|
|
{
|
|
"id": 2,
|
|
"state_id": 11,
|
|
"state_name": "包装",
|
|
"order": 1
|
|
},
|
|
{
|
|
"id": 3,
|
|
"state_id": 12,
|
|
"state_name": "发货",
|
|
"order": 2
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
### 3. 测试覆盖
|
|
|
|
#### 功能测试 (`stateflow/tests/test_services.py`)
|
|
|
|
新增测试: `test_get_process_nodes`
|
|
|
|
- ✅ 验证节点数量正确
|
|
- ✅ 验证节点顺序正确
|
|
- ✅ 验证节点字段完整性
|
|
- ✅ 验证每个节点包含必要字段
|
|
|
|
#### API 测试 (`stateflow/tests/test_business_object_api.py`)
|
|
|
|
新增测试: `test_get_process_nodes`
|
|
|
|
- ✅ 验证 HTTP 200 响应
|
|
- ✅ 验证响应包含 count 和 nodes 字段
|
|
- ✅ 验证节点数据格式正确
|
|
- ✅ 验证节点顺序和内容准确
|
|
|
|
### 4. 文档更新
|
|
|
|
#### API 文档 (`stateflow/API.md`)
|
|
|
|
新增章节: **3.7.5. 获取流程的所有节点**
|
|
|
|
- 📝 完整的接口说明
|
|
- 📝 请求/响应示例
|
|
- 📝 Python/JavaScript/curl 使用示例
|
|
|
|
## 测试结果
|
|
|
|
```bash
|
|
# 功能测试
|
|
$ python manage.py test stateflow.tests.test_services.StateFlowServicesTestCase.test_get_process_nodes
|
|
✅ OK
|
|
|
|
# API 测试
|
|
$ python manage.py test stateflow.tests.test_business_object_api.BusinessObjectAPITestCase.test_get_process_nodes
|
|
✅ OK
|
|
|
|
# 完整测试套件
|
|
$ python manage.py test stateflow
|
|
✅ Ran 80 tests in 11.122s - OK
|
|
```
|
|
|
|
## 使用示例
|
|
|
|
### Python
|
|
|
|
```python
|
|
import requests
|
|
|
|
headers = {'Authorization': f'Bearer {token}'}
|
|
response = requests.get(
|
|
'http://localhost:8000/api/v1/stateflow/business-objects/1/process-nodes/',
|
|
headers=headers
|
|
)
|
|
data = response.json()
|
|
|
|
print(f"流程共有 {data['count']} 个节点:")
|
|
for node in data['nodes']:
|
|
print(f" 节点 {node['order']}: {node['state_name']}")
|
|
```
|
|
|
|
### JavaScript
|
|
|
|
```javascript
|
|
const response = await fetch(
|
|
`/api/v1/stateflow/business-objects/${businessObjectId}/process-nodes/`,
|
|
{ headers: { 'Authorization': `Bearer ${token}` } }
|
|
);
|
|
const data = await response.json();
|
|
console.log(`流程共有 ${data.count} 个节点:`, data.nodes);
|
|
```
|
|
|
|
### curl
|
|
|
|
```bash
|
|
curl -X GET "http://localhost:8000/api/v1/stateflow/business-objects/1/process-nodes/" \
|
|
-H "Authorization: Bearer <token>"
|
|
```
|
|
|
|
## 应用场景
|
|
|
|
1. **前端流程可视化**: 获取完整的流程节点列表用于渲染流程图
|
|
2. **进度追踪**: 结合 timeline 接口展示完整的流程进度
|
|
3. **流程分析**: 分析流程包含的所有节点和顺序
|
|
4. **文档生成**: 自动生成流程说明文档
|
|
|
|
## 兼容性
|
|
|
|
- ✅ 完全向后兼容
|
|
- ✅ 不影响现有 API
|
|
- ✅ 所有现有测试通过 (80/80)
|
|
- ✅ 新增测试覆盖完整
|
|
|
|
## 相关文件
|
|
|
|
- `stateflow/services.py` - 新增 `get_process_nodes()` 函数
|
|
- `api_v1/views/stateflow/business_object.py` - 新增 `process_nodes()` action
|
|
- `stateflow/tests/test_services.py` - 新增功能测试
|
|
- `stateflow/tests/test_business_object_api.py` - 新增 API 测试
|
|
- `stateflow/API.md` - 更新文档
|
|
- `examples/test_process_nodes_api.py` - 使用示例
|
|
|
|
## 完成日期
|
|
|
|
2025-11-17
|