erpnew/stateflow/API.md

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

响应格式：

{
  "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）

示例：

curl -X GET "http://localhost:8000/api/v1/states/?search=审核&limit=10&offset=0" \
  -H "Authorization: Bearer <token>"

响应：

{
  "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}/

响应：

{
  "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/

请求体：

{
  "name": "待审核",
  "description": "等待审核",
  "parameters": [
    {
      "key": "timeout",
      "value": "24h",
      "description": "超时时间"
    }
  ]
}

响应：201 Created

{
  "name": "待审核",
  "description": "等待审核",
  "parameters": [...]
}

4. 更新状态

PUT /api/v1/states/{id}/

请求体：

{
  "name": "已审核",
  "description": "审核通过",
  "parameters": [
    {
      "key": "approver",
      "value": "admin",
      "description": "审核人"
    }
  ]
}

注意：parameters 数组会完全替换原有参数。

PATCH /api/v1/states/{id}/

部分更新，可以只更新某些字段：

{
  "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）

响应：

{
  "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}/

响应：

{
  "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/

请求体：

{
  "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}/

请求体：

{
  "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 遵循统一的错误响应格式：

{
  "detail": "错误描述"
}

或字段级错误：

{
  "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)

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)

// 获取状态列表
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

# 创建流程
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}
    ]
  }'