# Stateflow 状态流转系统

## 架构概述

Stateflow 是一个基于日志的订单状态流转管理系统，采用服务层模式实现业务逻辑与数据访问的分离。

### 核心概念

- **State (状态)**: 流程中的一个节点，可以附带参数
- **Process (流程模板)**: 由多个有序状态组成的流程定义
- **Order (订单实例)**: 流程的具体执行实例
- **OrderStateLog (完成日志)**: 记录订单完成每个状态的时间点和操作人

## 数据模型

### State
```python
State(name, parameters=[StateParameter(...)])
```
- 状态节点定义
- 支持附加参数（键值对）

### Process
```python
Process(name, state_nodes=ManyToMany[ProcessNode])
```
- 流程模板，定义状态流转顺序
- 通过 `ProcessNode` 中间表关联 `State`，支持排序

### ProcessNode
```python
ProcessNode(process, state, order)
```
- Process 和 State 的多对多关联表
- `order` 字段定义状态在流程中的执行顺序

### Order
```python
Order(process, metadata={})
```
- 流程的具体实例
- **不存储** `current_state` 字段
- 当前状态通过查询 `OrderStateLog` 推导

### OrderStateLog
```python
OrderStateLog(order, state, completed_at, completed_by, is_cancelled, cancelled_at)
```
- 记录订单完成某个状态的日志
- `completed_at`: 完成时间
- `completed_by`: 操作人
- `is_cancelled`: 是否已撤销
- `cancelled_at`: 撤销时间
- 唯一约束: `(order, state)` - 每个状态只能有一条记录
- **不允许删除**，重置进度时只标记为已撤销

## 核心逻辑

### 状态推导规则

当前状态的推导遵循以下规则：

1. **未开始**: 没有任何有效完成日志（或所有记录都被撤销） → 返回 `None`
2. **进行中**: 有部分完成日志 → 返回下一个未完成的状态
3. **已完成**: 所有状态都已完成 → 返回 `None`

**重要**: 初始状态是 `None`（未开始），而不是第一个节点。

示例：
```python
from stateflow.services import get_order_current_state, get_overall_status

# 获取当前状态（None = 未开始或已完成）
current_state = get_order_current_state(order)

# 获取整体状态类型
status = get_overall_status(order)  # 'not_started', 'in_progress', 'completed'
```

### 状态推进

```python
from stateflow.services import advance_to_next_state

# 推进到下一个状态（需要传入操作人）
success = advance_to_next_state(order, completed_by=request.user)
```

推进规则：
- 如果是初始状态（`None`），推进到第一个节点
- 自动查找当前状态
- 验证是否可以推进（是否已完成）
- 创建 `OrderStateLog` 记录完成时间和操作人
- 返回 `(True, message)` 表示成功，`(False, reason)` 表示失败

### 完整时间线

```python
from stateflow.services import get_order_state_timeline

# 获取完整的状态时间线
timeline = get_order_state_timeline(order)
# [
#   {'state': State1, 'completed_at': datetime, 'completed_by': User, 'is_completed': True},
#   {'state': State2, 'completed_at': None, 'completed_by': None, 'is_completed': False},
#   ...
# ]
```

## 服务层 API

所有业务逻辑封装在 `stateflow/services.py` 中，可在 Admin、API、任务队列等场景复用。

### 主要函数

#### `get_order_current_state(order) -> State | None`
获取订单当前应处理的状态。

#### `get_overall_status(order) -> str`
返回订单整体状态：
- `'not_started'`: 未开始
- `'in_progress'`: 进行中
- `'completed'`: 已完成

#### `get_order_state_status(order, state) -> str`
返回订单中某个状态的状态：
- `'not_started'`: 未开始
- `'in_progress'`: 进行中
- `'completed'`: 已完成

#### `advance_to_next_state(order, completed_by) -> Tuple[bool, str]`
推进到下一个状态，创建完成日志。返回 (是否成功, 消息)。

#### `get_order_state_timeline(order) -> List[dict]`
获取完整时间线，包含所有状态的完成情况（包括已撤销的记录）。

#### `get_progress_percentage(order) -> float`
计算完成进度百分比（0.0 - 100.0）。

#### `reset_order_progress(order)`
重置订单进度。注意：**不删除日志记录**，而是标记为已撤销并记录撤销时间，保留完整的操作历史。

#### `can_advance_to_next_state(order) -> Tuple[bool, str]`
检查是否可以继续推进。返回 (是否可以推进, 原因)。

## 使用示例

### 1. 创建流程模板

```python
from stateflow.models import State, Process, ProcessNode

# 创建状态
pending = State.objects.create(name="待审核")
approved = State.objects.create(name="已审核")
shipped = State.objects.create(name="已发货")

# 创建流程
process = Process.objects.create(name="订单流程")

# 关联状态（设置顺序）
ProcessNode.objects.create(process=process, state=pending, order=1)
ProcessNode.objects.create(process=process, state=approved, order=2)
ProcessNode.objects.create(process=process, state=shipped, order=3)
```

### 2. 创建订单并推进

```python
from stateflow.models import Order
from stateflow.services import get_order_current_state, advance_to_next_state, get_overall_status

# 创建订单实例
order = Order.objects.create(process=process, metadata={'order_no': 'SO-001'})

# 查看当前状态（初始状态是 None）
current = get_order_current_state(order)  # None
status = get_overall_status(order)  # 'not_started'

# 推进到第一个状态
success, msg = advance_to_next_state(order, completed_by=request.user)

current = get_order_current_state(order)  # approved

# 推进到下一个状态
success, msg = advance_to_next_state(order, completed_by=request.user)

current = get_order_current_state(order)  # shipped
```

### 3. 在 API 中使用

```python
from rest_framework.decorators import action
from rest_framework.response import Response
from stateflow.services import advance_to_next_state, get_order_state_timeline

class OrderViewSet(viewsets.ModelViewSet):
    
    @action(detail=True, methods=['post'])
    def advance(self, request, pk=None):
        order = self.get_object()
        success, message = advance_to_next_state(order, completed_by=request.user)
        
        if success:
            return Response({'status': 'advanced', 'message': message})
        return Response({'status': 'failed', 'message': message}, status=400)
    
    @action(detail=True, methods=['get'])
    def timeline(self, request, pk=None):
        order = self.get_object()
        timeline = get_order_state_timeline(order)
        return Response(timeline)
```

## Admin 配置

Admin 界面提供以下功能：

1. **State 管理**: 创建和编辑状态，支持内联编辑参数
2. **Process 管理**: 定义流程，通过内联表添加有序状态节点
3. **Order 管理**: 
   - 查看完成日志（只读内联）
   - 批量操作：推进到下一状态、重置进度
   - 显示当前状态、完成百分比
4. **OrderStateLog 管理**: 只读日志查看，用于审计

## 迁移历史

- `0001_initial.py`: 初始模型（State, Process with CharField state_nodes）
- `0002-0007`: 其他应用迁移
- `0008_process_state_nodes_remove_process_current_state...`: 将 state_nodes 改为 ManyToMany，创建 ProcessNode 和 Order
- `0009_remove_order_current_state_orderstatelog`: 移除 Order.current_state，创建 OrderStateLog

## 测试

运行测试：
```bash
python manage.py test stateflow
```

测试覆盖：
- ✅ 初始状态推导
- ✅ 状态推进逻辑
- ✅ 状态类型判断
- ✅ 完整时间线生成
- ✅ 进度重置

## 设计优势

1. **审计完整**: 每次状态变更都有时间和操作人记录
2. **数据一致**: 状态从日志推导，无冗余存储
3. **逻辑复用**: 服务层可在 Admin/API/Task 中共享
4. **灵活扩展**: 可轻松添加状态前置条件、权限检查等
5. **可追溯**: 通过 OrderStateLog 实现完整的操作历史
6. **历史保留**: 重置进度时不删除记录，保留完整的操作痕迹
7. **撤销追踪**: 记录撤销时间，方便审计和问题追溯

## ProcessNode vs OrderStateLog

很多人会混淆这两个表，这里做详细说明：

### ProcessNode (流程模板)
- **作用**: 定义流程包含哪些状态，以及执行顺序
- **关系**: Process ↔ State 的多对多关联
- **层级**: 模板层（一对多）
- **类比**: "菜谱"，定义做菜的步骤
- **示例**: 订单流程 = [待审核(1) → 已审核(2) → 已发货(3)]

### OrderStateLog (订单实例)
- **作用**: 记录某个订单完成了哪些状态，以及完成时间、操作人
- **关系**: Order → State 的完成记录
- **层级**: 实例层（每个订单独立）
- **类比**: "做菜记录"，记录实际做了什么、何时做的
- **示例**: 订单#001 在 2025-01-10 由张三完成了"待审核"状态

## 注意事项

1. **唯一约束**: 每个 `(order, state)` 只能有一条记录
2. **顺序性**: 必须按 ProcessNode.order 顺序完成，不能跳过
3. **操作人必填**: `advance_to_next_state()` 必须传入 `completed_by` 参数
4. **不可删除**: OrderStateLog 不允许删除，只能标记为已撤销
5. **保留历史**: 重置进度时保留所有历史记录，并记录撤销时间
6. **初始状态**: 新订单的初始状态是 `None`（未开始），而不是第一个节点