# 旧系统调度单同步功能说明

## 一、功能概述

在急救转运任务成功同步到旧系统（创建ServiceOrder）后，再将任务同步为调度单（DispatchOrder），将返回的DispatchOrdID保存到`sys_task_emergency`表中。

### 同步流程

```
创建急救转运任务
    ↓
同步到旧系统（admin_save_19.gds）
    ↓
获得ServiceOrdID，保存到legacy_service_ord_id
    ↓
同步调度单（admin_save_24.asp）
    ↓
获得DispatchOrdID，保存到legacy_dispatch_ord_id
```

## 二、数据库变更

### 新增字段

在`sys_task_emergency`表中添加以下字段：

```sql
-- 旧系统调度单ID
ALTER TABLE sys_task_emergency 
ADD COLUMN legacy_dispatch_ord_id BIGINT NULL COMMENT '旧系统调度单ID(DispatchOrdID)';

-- 调度单同步状态
ALTER TABLE sys_task_emergency 
ADD COLUMN dispatch_sync_status TINYINT DEFAULT 0 COMMENT '调度单同步状态：0-未同步，1-同步中，2-同步成功，3-同步失败';

-- 调度单同步时间
ALTER TABLE sys_task_emergency 
ADD COLUMN dispatch_sync_time DATETIME NULL COMMENT '调度单同步时间';

-- 调度单同步错误信息
ALTER TABLE sys_task_emergency 
ADD COLUMN dispatch_sync_error_msg VARCHAR(500) NULL COMMENT '调度单同步错误信息';
```

## 三、接口参数映射

### admin_save_24.asp 接口参数

根据ASP代码分析，主要参数包括：

| ASP参数 | 说明 | 数据来源 |
|---------|------|---------|
| DispatchOrdClass | 调度单类型 | sys_dept.dispatch_order_class |
| ServiceOrdID | 服务单ID | sys_task_emergency.legacy_service_ord_id |
| DispatchOrdTraSDTime | 拟出发时间 | sys_task.planned_start_time |
| DispatchOrdCarID | 派遣车辆ID | sys_task_vehicle → tb_vehicle_info.car_id |
| DispatchOrdCoName | 调度联系人姓名 | sys_task_emergency.patient_contact |
| DispatchOrdCoPhone | 调度联系人电话 | sys_task_emergency.patient_phone |
| DispatchOrdTraStreet | 实际出发地 | sys_task.departure_address |
| DispatchOrdTraEnd | 实际目的地 | sys_task.destination_address |
| DispatchOrd_Check | 操作命令 | 固定值"3"（直接强制完成） |
| DispatchOrdPerfomance | 订单绩效 | sys_task_emergency.transfer_price |
| DispatchOrd_NS_ID | 调度人员ID | sys_user.oa_user_id |
| DispatchOrd_NS_Time | 开单时间 | sys_task.create_time |

## 四、技术实现

### 4.1 核心类说明

#### 1. SysTaskEmergency实体类
**新增字段**：
- `legacyDispatchOrdId` - 旧系统调度单ID
- `dispatchSyncStatus` - 调度单同步状态
- `dispatchSyncTime` - 调度单同步时间
- `dispatchSyncErrorMsg` - 调度单同步错误信息

#### 2. ILegacySystemSyncService接口
**新增方法**：
```java
/**
 * 同步调度单到旧系统（admin_save_24.asp）
 */
Long syncDispatchOrderToLegacy(Long taskId);

/**
 * 批量同步未同步的调度单
 */
int batchSyncPendingDispatchOrders();
```

#### 3. LegacySystemSyncServiceImpl实现类
**核心方法**：
- `syncDispatchOrderToLegacy()` - 同步单个调度单
- `buildDispatchOrderParams()` - 构建调度单参数
- `batchSyncPendingDispatchOrders()` - 批量同步

**同步逻辑**：
1. 检查服务单是否已同步（必须先有ServiceOrdID）
2. 检查调度单是否已同步（避免重复）
3. 构建请求参数
4. 发送HTTP POST请求
5. 解析响应（格式：`OK:DispatchOrdID`）
6. 保存DispatchOrdID到数据库

#### 4. LegacySystemConfig配置类
**新增配置**：
```java
private String dispatchCreatePath = "/oldCode/admin_save_24.asp";

public String getDispatchCreateUrl() {
    return baseUrl + dispatchCreatePath;
}
```

#### 5. LegacySystemSyncTask定时任务
**新增方法**：
```java
public void syncPendingDispatchOrders() {
    // 批量同步未同步的调度单
}
```

### 4.2 同步状态管理

**dispatch_sync_status状态值**：
- `0` - 未同步
- `1` - 同步中
- `2` - 同步成功
- `3` - 同步失败

**查询条件**：
```sql
-- 查询待同步调度单的任务
SELECT * FROM sys_task_emergency
WHERE sync_status = 2  -- 服务单已同步
  AND legacy_service_ord_id IS NOT NULL
  AND (dispatch_sync_status = 0 OR dispatch_sync_status = 3)
LIMIT 100;
```

## 五、使用说明

### 5.1 自动同步

**配置定时任务**：
1. 进入「系统监控」→「定时任务」
2. 添加新任务：
   - 任务名称：旧系统调度单同步
   - 任务组名：DEFAULT
   - 调用目标：`legacySystemSyncTask.syncPendingDispatchOrders()`
   - cron表达式：`0 0/10 * * * ?`（每10分钟执行）

### 5.2 手动同步

**通过Service调用**：
```java
@Autowired
private ILegacySystemSyncService legacySystemSyncService;

// 同步单个调度单
Long dispatchOrdId = legacySystemSyncService.syncDispatchOrderToLegacy(taskId);

// 批量同步
int successCount = legacySystemSyncService.batchSyncPendingDispatchOrders();
```

### 5.3 查看同步结果

```sql
-- 查询调度单同步结果
SELECT 
    task_id,
    legacy_service_ord_id,
    legacy_dispatch_ord_id,
    dispatch_sync_status,
    dispatch_sync_time,
    dispatch_sync_error_msg
FROM sys_task_emergency
WHERE dispatch_sync_status IS NOT NULL
ORDER BY id DESC;

-- 统计同步情况
SELECT 
    dispatch_sync_status,
    COUNT(*) as count
FROM sys_task_emergency
WHERE legacy_service_ord_id IS NOT NULL
GROUP BY dispatch_sync_status;
```

## 六、完整同步流程

### 6.1 创建任务后的自动同步

```java
// 1. 创建急救转运任务
SysTask task = createEmergencyTask(...);

// 2. 同步服务单到旧系统
Long serviceOrdId = legacySystemSyncService.syncEmergencyTaskToLegacy(task.getTaskId());

// 3. 同步调度单到旧系统（需要在服务单同步成功后）
if (serviceOrdId != null && serviceOrdId > 0) {
    Long dispatchOrdId = legacySystemSyncService.syncDispatchOrderToLegacy(task.getTaskId());
}
```

### 6.2 定时任务自动重试

**定时任务1：同步服务单**
- 调用：`legacySystemSyncTask.syncPendingTasks()`
- 频率：每10分钟
- 处理：未同步或同步失败的服务单

**定时任务2：同步调度单**
- 调用：`legacySystemSyncTask.syncPendingDispatchOrders()`
- 频率：每10分钟
- 处理：已同步服务单但未同步调度单的任务

## 七、错误处理

### 7.1 常见错误

**错误1：服务单未同步**
```
错误信息：服务单未同步，无法同步调度单
解决方案：先确保服务单同步成功
```

**错误2：重复同步**
```
处理逻辑：自动跳过已同步的调度单
日志：调度单已同步过，任务ID: xxx, DispatchOrdID: xxx
```

**错误3：ASP接口返回错误**
```
错误信息：旧系统返回无效的DispatchOrdID: {response}
解决方案：检查ASP接口日志，查看具体错误原因
```

### 7.2 错误日志查看

```bash
# 查看同步日志
tail -f logs/sys-info.log | grep "调度单同步"

# 查看错误日志
tail -f logs/sys-error.log | grep "syncDispatchOrderToLegacy"
```

## 八、注意事项

### 8.1 同步顺序

⚠️ **必须先同步服务单，再同步调度单**

原因：调度单需要关联ServiceOrdID参数

### 8.2 数据依赖

**必需字段**：
- `legacy_service_ord_id` - 必须存在且大于0
- `patient_contact` - 联系人姓名（DispatchOrd_Check≠3时必填）
- `patient_phone` - 联系人电话（DispatchOrd_Check≠3时必填）

**可选字段**：
- `planned_start_time` - 拟出发时间
- `transfer_price` - 订单绩效

### 8.3 性能优化

1. **批量同步限制**：每次最多同步100条记录
2. **请求间隔**：每个请求间隔1秒，避免过于频繁
3. **超时设置**：连接超时30秒，读取超时30秒

## 九、测试验证

### 9.1 测试步骤

**步骤1：创建测试任务**
```sql
-- 确保任务已同步服务单
SELECT task_id, legacy_service_ord_id, sync_status
FROM sys_task_emergency
WHERE sync_status = 2
LIMIT 1;
```

**步骤2：手动触发同步**
```java
Long dispatchOrdId = legacySystemSyncService.syncDispatchOrderToLegacy(taskId);
```

**步骤3：验证结果**
```sql
SELECT 
    task_id,
    legacy_service_ord_id,
    legacy_dispatch_ord_id,
    dispatch_sync_status,
    dispatch_sync_error_msg
FROM sys_task_emergency
WHERE task_id = {taskId};
```

### 9.2 预期结果

| 字段 | 预期值 |
|------|--------|
| legacy_dispatch_ord_id | > 0 |
| dispatch_sync_status | 2（同步成功） |
| dispatch_sync_time | 当前时间 |
| dispatch_sync_error_msg | NULL |

## 十、相关文件清单

### 修改文件
1. `SysTaskEmergency.java` - 新增字段
2. `SysTaskEmergencyMapper.java` - 新增查询方法
3. `SysTaskEmergencyMapper.xml` - 新增SQL语句
4. `ILegacySystemSyncService.java` - 新增接口方法
5. `LegacySystemSyncServiceImpl.java` - 实现调度单同步逻辑
6. `LegacySystemConfig.java` - 新增配置项
7. `LegacySystemSyncTask.java` - 新增定时任务方法

### SQL文件
8. `add_legacy_dispatch_ord_id.sql` - 数据库变更脚本

### 文档
9. `旧系统调度单同步功能说明.md` - 本文档

## 十一、后续优化建议

1. **车辆关联**：从`sys_task_vehicle`表查询车辆，获取`car_id`填充`DispatchOrdCarID`参数
2. **人员关联**：支持随行人员（EntourageID）的同步
3. **重试机制**：增加指数退避的重试策略
4. **监控告警**：同步失败时发送通知
5. **数据校验**：同步前校验必填字段完整性

---

**版本**：v1.0  
**日期**：2025-10-20  
**作者**：Qoder AI