# 新增功能：获取业务对象流程节点接口

## 概述

为 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