# 任务状态流转规则说明

## 📋 概述

本文档说明转运任务的状态流转规则，包括正常流程和兼容旧数据的特殊规则。

---

## 🔄 状态定义

### 标准状态（新系统）

| 状态码 | 状态名称 | 说明 | 样式 |
|--------|---------|------|------|
| `PENDING` | 待处理 | 任务已创建，等待出发 | warning |
| `DEPARTING` | 出发中 | 任务已出发，前往目的地 | primary |
| `ARRIVED` | 已到达 | 已到达目的地 | primary |
| `RETURNING` | 返程中 | 任务返程中 | primary |
| `COMPLETED` | 已完成 | 任务已完成（终态） | success |
| `CANCELLED` | 已取消 | 任务已取消（终态） | danger |

### 兼容状态（旧系统）

| 状态码 | 状态名称 | 说明 | 来源 |
|--------|---------|------|------|
| `IN_PROGRESS` | 任务中 | 任务执行中（兼容旧数据） | 旧系统状态码6 |

---

## 🚦 状态流转规则

### 1. 正常流程

```mermaid
graph LR
    A[PENDING<br/>待处理] --> B[DEPARTING<br/>出发中]
    B --> C[ARRIVED<br/>已到达]
    C --> D[RETURNING<br/>返程中]
    D --> E[COMPLETED<br/>已完成]
    
    A -.取消.-> F[CANCELLED<br/>已取消]
    B -.取消.-> F
    C -.取消.-> F
```

**流转路径**：
- `PENDING` → `DEPARTING` → `ARRIVED` → `RETURNING` → `COMPLETED`
- 任何状态（除COMPLETED外）→ `CANCELLED`

---

### 2. 兼容旧数据流程

```mermaid
graph TD
    A[IN_PROGRESS<br/>任务中<br/>旧数据] --> B[PENDING<br/>待处理]
    A --> C[ARRIVED<br/>已到达]
    A --> D[RETURNING<br/>返程中]
    A --> E[COMPLETED<br/>已完成]
    A --> F[CANCELLED<br/>已取消]
    
    style A fill:#ffeaa7,stroke:#fdcb6e
    style B fill:#74b9ff,stroke:#0984e3
    style C fill:#74b9ff,stroke:#0984e3
    style D fill:#74b9ff,stroke:#0984e3
    style E fill:#55efc4,stroke:#00b894
    style F fill:#ff7675,stroke:#d63031
```

**说明**：
- `IN_PROGRESS` 是为了兼容旧系统的"服务中"状态（状态码6）
- 允许向**5个状态**转换，提供最大灵活性
- 主要用于数据迁移和双系统并行期间

---

## 📝 详细流转规则

### PENDING（待处理）
✅ **允许转换到**：
- `DEPARTING`（出发中）- 开始执行任务
- `CANCELLED`（已取消）- 取消任务

❌ **不允许转换到**：其他所有状态

---

### DEPARTING（出发中）
✅ **允许转换到**：
- `ARRIVED`（已到达）- 到达目的地
- `CANCELLED`（已取消）- 取消任务

❌ **不允许转换到**：其他所有状态

---

### ARRIVED（已到达）
✅ **允许转换到**：
- `RETURNING`（返程中）- 开始返程

❌ **不允许转换到**：其他所有状态

**注意**：已到达后只能返程，不能直接完成或取消

---

### RETURNING（返程中）
✅ **允许转换到**：
- `COMPLETED`（已完成）- 完成返程

❌ **不允许转换到**：其他所有状态

---

### IN_PROGRESS（任务中）⚠️
✅ **允许转换到**：
- `PENDING`（待处理）- 数据修正
- `ARRIVED`（已到达）- 补充状态
- `RETURNING`（返程中）- 进入返程 ⭐ **新增**
- `COMPLETED`（已完成）- 强制完成
- `CANCELLED`（已取消）- 取消任务

❌ **不允许转换到**：其他所有状态

**使用场景**：
1. 旧系统数据迁移
2. 状态补偿修正
3. 特殊业务流程

---

### COMPLETED（已完成）
✅ **允许转换到**：无

❌ **不允许转换到**：任何状态

**说明**：终态，不允许任何变更

---

### CANCELLED（已取消）
✅ **允许转换到**：无

❌ **不允许转换到**：任何状态

**说明**：终态，不允许任何变更

---

## 💻 代码实现

### 方法1: SysTask.canChangeStatus()
```java
public boolean canChangeStatus(TaskStatus newStatus) {
    TaskStatus currentStatus = TaskStatus.getByCode(this.taskStatus);
    
    switch (currentStatus) {
        case IN_PROGRESS:
            // 兼容旧数据：任务中 -> 已完成、已取消、待处理、已到达、返程中
            return newStatus == TaskStatus.COMPLETED 
                || newStatus == TaskStatus.CANCELLED 
                || newStatus == TaskStatus.PENDING 
                || newStatus == TaskStatus.ARRIVED
                || newStatus == TaskStatus.RETURNING;
        // ... 其他状态
    }
}
```

### 方法2: TaskStatusValidator.canTransition()
```java
// IN_PROGRESS -> COMPLETED, CANCELLED, PENDING, ARRIVED, RETURNING
Set<TaskStatus> inProgressTransitions = new HashSet<>();
inProgressTransitions.add(TaskStatus.COMPLETED);
inProgressTransitions.add(TaskStatus.CANCELLED);
inProgressTransitions.add(TaskStatus.PENDING);
inProgressTransitions.add(TaskStatus.ARRIVED);
inProgressTransitions.add(TaskStatus.RETURNING);
ALLOWED_TRANSITIONS.put(TaskStatus.IN_PROGRESS, inProgressTransitions);
```

---

## 🔍 常见问题

### Q1: 为什么IN_PROGRESS可以转换到这么多状态？
**A**: 因为IN_PROGRESS是旧系统的"服务中"状态，旧系统的状态粒度较粗，无法准确对应新系统的细分状态。为了兼容旧数据和保证业务连续性，允许向多个状态转换。

### Q2: 新建的任务会是IN_PROGRESS状态吗？
**A**: 不会。新系统创建的任务初始状态是PENDING，正常流转不会经过IN_PROGRESS。IN_PROGRESS只用于：
1. 旧系统数据同步
2. 历史数据迁移
3. 数据修正场景

### Q3: IN_PROGRESS能直接到COMPLETED吗？
**A**: 可以。通过"强制完成"按钮可以直接完成任务，跳过中间状态。

### Q4: 如何判断任务是否可以操作？
**A**: 使用 `canChangeStatus(newStatus)` 方法：
```java
SysTask task = ...;
if (task.canChangeStatus(TaskStatus.RETURNING)) {
    // 允许转换到返程中
}
```

---

## 📊 状态流转矩阵

| 当前状态 ↓ / 目标状态 → | PENDING | DEPARTING | ARRIVED | RETURNING | COMPLETED | CANCELLED | IN_PROGRESS |
|------------------------|---------|-----------|---------|-----------|-----------|-----------|-------------|
| **PENDING**            | -       | ✅         | ❌      | ❌         | ❌         | ✅         | ❌           |
| **DEPARTING**          | ❌      | -         | ✅       | ❌         | ❌         | ✅         | ❌           |
| **ARRIVED**            | ❌      | ❌        | -       | ✅         | ❌         | ❌         | ❌           |
| **RETURNING**          | ❌      | ❌        | ❌      | -         | ✅         | ❌         | ❌           |
| **IN_PROGRESS** ⚠️     | ✅      | ❌        | ✅       | ✅ ⭐      | ✅         | ✅         | -           |
| **COMPLETED**          | ❌      | ❌        | ❌      | ❌         | -         | ❌         | ❌           |
| **CANCELLED**          | ❌      | ❌        | ❌      | ❌         | ❌         | -         | ❌           |

**图例**：
- ✅ 允许转换
- ❌ 不允许转换
- ⭐ 本次新增
- ⚠️ 兼容旧数据

---

## 🔧 相关文件

### 代码文件
- [SysTask.java](file:///d:/project/急救转运/code/Api/RuoYi-Vue-master/ruoyi-system/src/main/java/com/ruoyi/system/domain/SysTask.java) - 任务实体，包含canChangeStatus方法
- [TaskStatusValidator.java](file:///d:/project/急救转运/code/Api/RuoYi-Vue-master/ruoyi-system/src/main/java/com/ruoyi/system/utils/TaskStatusValidator.java) - 状态验证器
- [TaskStatus.java](file:///d:/project/急救转运/code/Api/RuoYi-Vue-master/ruoyi-system/src/main/java/com/ruoyi/system/domain/enums/TaskStatus.java) - 状态枚举

### SQL文件
- [update_task_status_dict.sql](file:///d:/project/急救转运/code/Api/RuoYi-Vue-master/sql/update_task_status_dict.sql) - 状态字典初始化

### 前端文件
- [detail.vue](file:///d:/project/急救转运/code/Api/RuoYi-Vue-master/app/pagesTask/detail.vue) - 任务详情页（包含状态按钮）

---

## 📅 更新记录

| 日期 | 版本 | 说明 | 修改人 |
|------|------|------|--------|
| 2026-01-12 | v1.1 | 新增 IN_PROGRESS → RETURNING 流转规则 | Qoder |
| 2025-01-XX | v1.0 | 初始版本，定义基础状态流转规则 | - |

---

**文档版本**: v1.1  
**最后更新**: 2026-01-12  
**维护人**: Qoder AI Assistant