966120
编辑 | blame | 历史 | 原始文档

任务状态流转规则说明

📋 概述

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

🔄 状态定义

标准状态（新系统）

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

兼容状态（旧系统）

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

🚦 状态流转规则

1. 正常流程

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. 兼容旧数据流程

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()

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()

// 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 | ❌ | ❌ | ❌ | ❌ | ❌ | - | ❌ |

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

🔧 相关文件

代码文件

SQL文件

前端文件

  • detail.vue - 任务详情页（包含状态按钮）

📅 更新记录

日期 版本 说明 修改人
2026-01-12 v1.1 新增 IN_PROGRESS → RETURNING 流转规则 Qoder

| 2025-01-XX | v1.0 | 初始版本，定义基础状态流转规则 | - |

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