forked from erp-dev/erp
feat: new modul (stateflow)
This commit is contained in:
390
stateflow/API.md
Normal file
390
stateflow/API.md
Normal file
@@ -0,0 +1,390 @@
|
||||
# Stateflow API 文档
|
||||
|
||||
## 概述
|
||||
|
||||
Stateflow API 提供了状态节点和流程的 CRUD 操作接口。
|
||||
|
||||
## 基础 URL
|
||||
|
||||
```
|
||||
/api/v1/
|
||||
```
|
||||
|
||||
## 认证
|
||||
|
||||
所有 API 都需要 JWT 认证。在请求头中添加：
|
||||
|
||||
```
|
||||
Authorization: Bearer <access_token>
|
||||
```
|
||||
|
||||
## 分页
|
||||
|
||||
使用 LimitOffset 分页：
|
||||
|
||||
- `limit`: 返回结果数量（默认无限制）
|
||||
- `offset`: 偏移量（默认0）
|
||||
|
||||
示例：
|
||||
```
|
||||
GET /api/v1/states/?limit=10&offset=0
|
||||
```
|
||||
|
||||
响应格式：
|
||||
```json
|
||||
{
|
||||
"count": 100,
|
||||
"next": "http://example.com/api/v1/states/?limit=10&offset=10",
|
||||
"previous": null,
|
||||
"results": [...]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## State API (状态节点)
|
||||
|
||||
### 1. 列表查询
|
||||
|
||||
**GET** `/api/v1/states/`
|
||||
|
||||
查询参数：
|
||||
- `limit`: 分页限制
|
||||
- `offset`: 分页偏移
|
||||
- `name`: 按名称精确查询
|
||||
- `search`: 全文搜索（名称和描述）
|
||||
- `ordering`: 排序字段（id, name, created_at, updated_at）
|
||||
|
||||
示例：
|
||||
```bash
|
||||
curl -X GET "http://localhost:8000/api/v1/states/?search=审核&limit=10&offset=0" \
|
||||
-H "Authorization: Bearer <token>"
|
||||
```
|
||||
|
||||
响应：
|
||||
```json
|
||||
{
|
||||
"count": 1,
|
||||
"next": null,
|
||||
"previous": null,
|
||||
"results": [
|
||||
{
|
||||
"id": 1,
|
||||
"name": "待审核",
|
||||
"description": "等待审核",
|
||||
"created_at": "2025-01-01T00:00:00Z",
|
||||
"updated_at": "2025-01-01T00:00:00Z"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### 2. 详情查询
|
||||
|
||||
**GET** `/api/v1/states/{id}/`
|
||||
|
||||
响应：
|
||||
```json
|
||||
{
|
||||
"id": 1,
|
||||
"name": "待审核",
|
||||
"description": "等待审核",
|
||||
"parameters": [
|
||||
{
|
||||
"id": 1,
|
||||
"key": "timeout",
|
||||
"value": "24h",
|
||||
"description": "超时时间"
|
||||
}
|
||||
],
|
||||
"created_at": "2025-01-01T00:00:00Z",
|
||||
"updated_at": "2025-01-01T00:00:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
### 3. 创建状态
|
||||
|
||||
**POST** `/api/v1/states/`
|
||||
|
||||
请求体：
|
||||
```json
|
||||
{
|
||||
"name": "待审核",
|
||||
"description": "等待审核",
|
||||
"parameters": [
|
||||
{
|
||||
"key": "timeout",
|
||||
"value": "24h",
|
||||
"description": "超时时间"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
响应：`201 Created`
|
||||
```json
|
||||
{
|
||||
"name": "待审核",
|
||||
"description": "等待审核",
|
||||
"parameters": [...]
|
||||
}
|
||||
```
|
||||
|
||||
### 4. 更新状态
|
||||
|
||||
**PUT** `/api/v1/states/{id}/`
|
||||
|
||||
请求体：
|
||||
```json
|
||||
{
|
||||
"name": "已审核",
|
||||
"description": "审核通过",
|
||||
"parameters": [
|
||||
{
|
||||
"key": "approver",
|
||||
"value": "admin",
|
||||
"description": "审核人"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
注意：`parameters` 数组会完全替换原有参数。
|
||||
|
||||
**PATCH** `/api/v1/states/{id}/`
|
||||
|
||||
部分更新，可以只更新某些字段：
|
||||
```json
|
||||
{
|
||||
"description": "新的描述"
|
||||
}
|
||||
```
|
||||
|
||||
### 5. 删除状态
|
||||
|
||||
**DELETE** `/api/v1/states/{id}/`
|
||||
|
||||
响应：`204 No Content`
|
||||
|
||||
---
|
||||
|
||||
## Process API (流程)
|
||||
|
||||
### 1. 列表查询
|
||||
|
||||
**GET** `/api/v1/processes/`
|
||||
|
||||
查询参数：
|
||||
- `limit`: 分页限制
|
||||
- `offset`: 分页偏移
|
||||
- `name`: 按名称精确查询
|
||||
- `search`: 全文搜索（名称和描述）
|
||||
- `ordering`: 排序字段（id, name, node_count, created_at, updated_at）
|
||||
|
||||
响应：
|
||||
```json
|
||||
{
|
||||
"count": 2,
|
||||
"next": null,
|
||||
"previous": null,
|
||||
"results": [
|
||||
{
|
||||
"id": 1,
|
||||
"name": "订单流程",
|
||||
"description": "标准订单处理流程",
|
||||
"node_count": 3,
|
||||
"created_at": "2025-01-01T00:00:00Z",
|
||||
"updated_at": "2025-01-01T00:00:00Z"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### 2. 详情查询
|
||||
|
||||
**GET** `/api/v1/processes/{id}/`
|
||||
|
||||
响应：
|
||||
```json
|
||||
{
|
||||
"id": 1,
|
||||
"name": "订单流程",
|
||||
"description": "标准订单处理流程",
|
||||
"nodes": [
|
||||
{
|
||||
"id": 1,
|
||||
"state_id": 1,
|
||||
"state_name": "待审核",
|
||||
"order": 0
|
||||
},
|
||||
{
|
||||
"id": 2,
|
||||
"state_id": 2,
|
||||
"state_name": "已审核",
|
||||
"order": 1
|
||||
},
|
||||
{
|
||||
"id": 3,
|
||||
"state_id": 3,
|
||||
"state_name": "已发货",
|
||||
"order": 2
|
||||
}
|
||||
],
|
||||
"created_at": "2025-01-01T00:00:00Z",
|
||||
"updated_at": "2025-01-01T00:00:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
### 3. 创建流程
|
||||
|
||||
**POST** `/api/v1/processes/`
|
||||
|
||||
请求体：
|
||||
```json
|
||||
{
|
||||
"name": "订单流程",
|
||||
"description": "标准订单处理流程",
|
||||
"nodes": [
|
||||
{
|
||||
"state_id": 1,
|
||||
"order": 0
|
||||
},
|
||||
{
|
||||
"state_id": 2,
|
||||
"order": 1
|
||||
},
|
||||
{
|
||||
"state_id": 3,
|
||||
"order": 2
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
响应：`201 Created`
|
||||
|
||||
### 4. 更新流程
|
||||
|
||||
**PUT** `/api/v1/processes/{id}/`
|
||||
|
||||
请求体：
|
||||
```json
|
||||
{
|
||||
"name": "更新后的流程",
|
||||
"description": "新的描述",
|
||||
"nodes": [
|
||||
{
|
||||
"state_id": 2,
|
||||
"order": 0
|
||||
},
|
||||
{
|
||||
"state_id": 3,
|
||||
"order": 1
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
注意：`nodes` 数组会完全替换原有节点。
|
||||
|
||||
**PATCH** `/api/v1/processes/{id}/`
|
||||
|
||||
部分更新。
|
||||
|
||||
### 5. 删除流程
|
||||
|
||||
**DELETE** `/api/v1/processes/{id}/`
|
||||
|
||||
响应：`204 No Content`
|
||||
|
||||
---
|
||||
|
||||
## 错误响应
|
||||
|
||||
所有 API 遵循统一的错误响应格式：
|
||||
|
||||
```json
|
||||
{
|
||||
"detail": "错误描述"
|
||||
}
|
||||
```
|
||||
|
||||
或字段级错误：
|
||||
|
||||
```json
|
||||
{
|
||||
"name": ["该字段不能为空"],
|
||||
"nodes": [
|
||||
{
|
||||
"state_id": ["状态ID 999 不存在"]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
常见状态码：
|
||||
- `200 OK`: 成功
|
||||
- `201 Created`: 创建成功
|
||||
- `204 No Content`: 删除成功
|
||||
- `400 Bad Request`: 请求参数错误
|
||||
- `401 Unauthorized`: 未认证
|
||||
- `403 Forbidden`: 无权限
|
||||
- `404 Not Found`: 资源不存在
|
||||
- `500 Internal Server Error`: 服务器错误
|
||||
|
||||
## 示例代码
|
||||
|
||||
### Python (requests)
|
||||
|
||||
```python
|
||||
import requests
|
||||
|
||||
# 获取 token
|
||||
response = requests.post('http://localhost:8000/api/token/', {
|
||||
'username': 'admin',
|
||||
'password': 'password'
|
||||
})
|
||||
token = response.json()['access']
|
||||
|
||||
# 创建状态
|
||||
headers = {'Authorization': f'Bearer {token}'}
|
||||
response = requests.post(
|
||||
'http://localhost:8000/api/v1/states/',
|
||||
json={
|
||||
'name': '待审核',
|
||||
'description': '等待审核'
|
||||
},
|
||||
headers=headers
|
||||
)
|
||||
state = response.json()
|
||||
```
|
||||
|
||||
### JavaScript (fetch)
|
||||
|
||||
```javascript
|
||||
// 获取状态列表
|
||||
const response = await fetch('/api/v1/states/?limit=10&offset=0', {
|
||||
headers: {
|
||||
'Authorization': `Bearer ${token}`
|
||||
}
|
||||
});
|
||||
const data = await response.json();
|
||||
console.log(data.results);
|
||||
```
|
||||
|
||||
### curl
|
||||
|
||||
```bash
|
||||
# 创建流程
|
||||
curl -X POST "http://localhost:8000/api/v1/processes/" \
|
||||
-H "Authorization: Bearer <token>" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"name": "订单流程",
|
||||
"description": "标准订单处理流程",
|
||||
"nodes": [
|
||||
{"state_id": 1, "order": 0},
|
||||
{"state_id": 2, "order": 1}
|
||||
]
|
||||
}'
|
||||
```
|
||||
Reference in New Issue
Block a user