# 旧系统任务状态同步功能说明

## 📋 功能概述

实现从旧系统同步任务状态到新系统，确保新旧系统的任务状态保持一致。当旧系统操作人员更新调度单状态后，新系统能够自动获取最新状态并更新本地任务。

## 🎯 业务场景

1. **状态实时更新**: 旧系统司机/医护人员更新了任务状态，新系统需要同步显示
2. **双系统并行**: 新旧系统同时使用期间，保持数据一致性
3. **状态监控**: 通过新系统监控旧系统任务执行情况

## 📊 状态映射规则

### 旧系统 → 新系统状态映射

| 旧系统状态 | 状态码 | 新系统状态 | 说明 |
|---------|-------|---------|------|
| 新调度单（未下发） | 0 | PENDING | 待处理 |
| 完全未确认 | 1 | PENDING | 待处理 |
| 部分已确认 | 2 | PENDING | 待处理 |
| 未出车 | 3 | PENDING | 待处理 |
| 已出车（去接患者途中） | 4 | DEPARTING | 出发中 |
| 已出车（等待患者） | 5 | ARRIVED | 已到达 |
| 已出车（服务中） | 6 | IN_PROGRESS | 任务中 |
| 已送达（回程中） | 7 | RETURNING | 返程中 |
| 已返回 | 8 | COMPLETED | 已完成 |
| 跑空单，已返回 | 9 | COMPLETED | 已完成 |
| 取消 | 10 | CANCELLED | 已取消 |
| 已提交，等待审核 | 11 | PENDING | 待处理 |
| 审核完成 | 12 | PENDING | 待处理 |
| 审核不通过 | 13 | CANCELLED | 已取消 |
| 已驻点 | 14 | ARRIVED | 已到达 |

## 🔧 技术实现

### 1. 核心文件

#### 状态转换工具类
- **文件**: `TaskStatusConverter.java`
- **位置**: `ruoyi-system/src/main/java/com/ruoyi/system/utils/`
- **功能**: 
  - 旧系统状态码转新系统状态枚举
  - 新系统状态枚举转旧系统状态码
  - 状态描述查询

```java
// 使用示例
TaskStatus newStatus = TaskStatusConverter.convertFromLegacyStatus(4);
// 返回: TaskStatus.DEPARTING

Integer legacyCode = TaskStatusConverter.convertToLegacyStatus(TaskStatus.DEPARTING);
// 返回: 4

String description = TaskStatusConverter.getLegacyStatusDescription(4);
// 返回: "已出车（去接患者途中）"
```

#### 同步服务接口
- **接口**: `ILegacySystemSyncService.java`
- **实现**: `LegacySystemSyncServiceImpl.java`
- **新增方法**:
  - `syncTaskStatusFromLegacy(Long taskId)`: 同步单个任务状态
  - `batchSyncTaskStatusFromLegacy()`: 批量同步任务状态

#### 定时任务
- **文件**: `LegacySystemSyncTask.java`
- **位置**: `ruoyi-quartz/src/main/java/com/ruoyi/quartz/task/`
- **方法**: `syncTaskStatusFromLegacy()`
- **执行频率**: 建议每5分钟一次

### 2. 配置文件

#### 旧系统配置
```yaml
# application.yml
legacy:
  system:
    base-url: http://legacy-system.com
    status-query-path: /task_status_query.asp  # 新增状态查询接口路径
    enabled: true
```

#### 定时任务配置
执行SQL脚本: `sql/legacy_status_sync_job.sql`

```sql
-- 任务配置
任务名称: 任务状态同步
调用目标: legacySystemSyncTask.syncTaskStatusFromLegacy()
Cron表达式: 0 0/5 * * * ? (每5分钟执行一次)
```

### 3. 同步流程

```mermaid
graph TB
    A[定时任务启动] --> B[查询需同步任务]
    B --> C{是否有任务}
    C -->|是| D[遍历任务列表]
    C -->|否| E[结束]
    D --> F[查询旧系统状态]
    F --> G{查询成功?}
    G -->|是| H[状态码转换]
    G -->|否| I[记录错误日志]
    H --> J{状态是否变化?}
    J -->|是| K[更新任务状态]
    J -->|否| L[跳过更新]
    K --> M[设置时间戳]
    M --> N[保存任务]
    L --> D
    N --> D
    I --> D
    D --> O{是否完成}
    O -->|否| D
    O -->|是| P[统计同步结果]
    P --> E
```

### 4. 数据库查询

#### Mapper新增方法
```xml
<!-- 查询已同步调度单且状态未完成的任务 -->
<select id="selectSyncedTasksForStatusUpdate" resultMap="SysTaskEmergencyResult">
    SELECT * FROM sys_task_emergency
    WHERE dispatch_sync_status = 2 
      AND legacy_dispatch_ord_id IS NOT NULL
      AND task_id IN (
          SELECT task_id FROM sys_task 
          WHERE task_status NOT IN ('COMPLETED', 'CANCELLED')
            AND del_flag = '0'
      )
    ORDER BY id ASC
    LIMIT 200
</select>
```

## 🚀 部署步骤

### 1. 代码部署
```bash
# 重新编译项目
mvn clean package

# 重启应用
./ry.sh restart
```

### 2. 配置旧系统接口

确保旧系统提供状态查询接口，接口规范:
- **URL**: `/task_status_query.asp`
- **方法**: POST
- **参数**: `DispatchOrdID` (调度单ID)
- **响应格式**: 
  - 成功: `OK:状态码` (如: `OK:4`)
  - 失败: `ERROR:错误信息`

### 3. 添加定时任务

执行SQL脚本:
```bash
mysql -u root -p your_database < sql/legacy_status_sync_job.sql
```

或在系统管理界面手动添加:
1. 登录系统管理后台
2. 进入 `系统管理` -> `定时任务`
3. 点击 `新增`
4. 填写任务信息:
   - 任务名称: 任务状态同步
   - 调用目标字符串: `legacySystemSyncTask.syncTaskStatusFromLegacy()`
   - Cron表达式: `0 0/5 * * * ?`
   - 状态: 正常
5. 保存并启动任务

### 4. 验证功能

#### 手动触发测试
```java
// 在定时任务管理页面点击"执行一次"按钮
// 或在代码中调用
@Autowired
private ILegacySystemSyncService legacySystemSyncService;

// 同步单个任务
boolean success = legacySystemSyncService.syncTaskStatusFromLegacy(taskId);

// 批量同步
int count = legacySystemSyncService.batchSyncTaskStatusFromLegacy();
```

#### 查看同步结果
```sql
-- 查看最近同步的任务
SELECT 
    t.task_id,
    t.task_code,
    t.task_status,
    e.legacy_dispatch_ord_id,
    t.update_time
FROM sys_task t
INNER JOIN sys_task_emergency e ON t.task_id = e.task_id
WHERE e.dispatch_sync_status = 2
ORDER BY t.update_time DESC
LIMIT 20;
```

#### 查看日志
```bash
# 查看应用日志
tail -f logs/sys-info.log | grep "任务状态同步"
```

## 📝 同步规则

### 同步条件
任务需要满足以下所有条件才会被同步:
1. ✅ 调度单已同步成功 (`dispatch_sync_status = 2`)
2. ✅ 存在旧系统调度单ID (`legacy_dispatch_ord_id IS NOT NULL`)
3. ✅ 任务状态未完成 (`task_status NOT IN ('COMPLETED', 'CANCELLED')`)
4. ✅ 任务未删除 (`del_flag = '0'`)

### 状态更新规则
1. **状态相同**: 不更新，跳过
2. **状态不同**: 更新任务状态，并设置时间戳:
   - `DEPARTING/ARRIVED/IN_PROGRESS`: 设置 `actual_start_time`
   - `COMPLETED/CANCELLED`: 设置 `actual_start_time` 和 `actual_end_time`

### 防重复机制
- 每次同步前检查状态是否变化
- 状态未变化则跳过更新，避免无效操作

## ⚠️ 注意事项

### 1. 依赖关系
- **前置条件**: 必须先完成调度单同步
- **执行顺序**: 
  1. 服务单同步 (admin_save_19.gds)
  2. 调度单同步 (admin_save_24.gds)
  3. 状态同步 (task_status_query.asp) ← 当前功能

### 2. 性能优化
- 每次最多查询200个任务
- 请求间隔0.5秒，避免频繁请求
- 仅同步未完成状态的任务

### 3. 错误处理
- 查询失败记录错误日志
- 不影响其他任务的同步
- 下次定时任务继续尝试

### 4. 监控建议
- 定期检查定时任务执行日志
- 监控同步成功率
- 关注状态转换异常

## 🔍 故障排查

### 问题1: 状态未同步

**可能原因**:
1. 定时任务未启动
2. 旧系统接口不可用
3. 任务不满足同步条件

**排查步骤**:
```sql
-- 1. 检查定时任务状态
SELECT * FROM sys_job WHERE job_name = '任务状态同步';

-- 2. 检查任务同步状态
SELECT 
    e.task_id,
    e.dispatch_sync_status,
    e.legacy_dispatch_ord_id,
    t.task_status
FROM sys_task_emergency e
INNER JOIN sys_task t ON e.task_id = t.task_id
WHERE e.task_id = 'YOUR_TASK_ID';

-- 3. 查看错误日志
-- tail -f logs/sys-error.log | grep "状态同步"
```

### 问题2: 状态映射错误

**解决方案**:
检查 `TaskStatusConverter.java` 的映射规则是否正确

### 问题3: 性能问题

**优化建议**:
- 调整定时任务执行频率
- 减少每批查询的任务数量
- 增加请求间隔时间

## 📚 相关文档

- [任务状态流转合法性规则](../任务状态.md)
- [旧系统同步功能实现总结](旧系统同步功能实现总结.md)
- [旧系统同步参数映射表](旧系统同步参数映射表.md)

## 🔄 版本历史

- **v1.0** (2025-01-30)
  - 实现基础状态同步功能
  - 支持新旧系统状态映射
  - 添加定时任务自动同步
  - 完善错误处理和日志记录