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
```

响应格式：
```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}
    ]
  }'
```