# 旧系统同步功能配置说明

## 一、功能概述

本功能实现了新系统的急救转运任务自动同步到旧ASP系统的能力。主要包括:

1. **自动同步**: 创建急救转运任务后，自动异步调用旧系统接口
2. **定时同步**: 通过定时任务批量同步未同步成功的任务
3. **手动重试**: 支持手动重新同步失败的任务
4. **状态跟踪**: 记录每个任务的同步状态和错误信息

## 二、数据库配置

### 1. 执行SQL脚本

```bash
mysql -u root -p ruoyi < sql/add_legacy_system_id.sql
```

该脚本会在 `sys_task_emergency` 表中添加以下字段:
- `legacy_service_ord_id`: 旧系统ServiceOrdID
- `sync_status`: 同步状态 (0-未同步, 1-同步中, 2-同步成功, 3-同步失败)
- `sync_time`: 同步时间
- `sync_error_msg`: 同步错误信息

在 `sys_task` 表中添加:
- `legacy_synced`: 旧系统同步标记 (0-未同步, 1-已同步)

## 三、应用配置

### 1. 在 `application.yml` 中添加配置

```yaml
# 旧系统配置
legacy:
  system:
    # 旧系统基础URL (必须配置)
    base-url: http://old-system.example.com
    
    # 急救转运创建接口路径 (默认值，可不配置)
    emergency-create-path: /admin_save_19.gds
    
    # 连接超时时间(毫秒) (默认30秒)
    connect-timeout: 30000
    
    # 读取超时时间(毫秒) (默认30秒)
    read-timeout: 30000
    
    # 是否启用同步 (true=启用, false=禁用)
    enabled: true
    
    # 字符编码 (默认UTF-8)
    charset: UTF-8
```

### 2. 配置示例

**开发环境** (`application-dev.yml`):
```yaml
legacy:
  system:
    base-url: http://192.168.1.100:8080
    enabled: true
```

**生产环境** (`application-prod.yml`):
```yaml
legacy:
  system:
    base-url: http://legacy.yourdomain.com
    enabled: true
```

**测试环境** (禁用同步):
```yaml
legacy:
  system:
    enabled: false
```

## 四、定时任务配置

### 1. 登录后台管理系统

访问: `系统管理` -> `定时任务` -> `新增`

### 2. 添加定时任务

填写以下信息:

| 字段 | 值 |
|-----|-----|
| 任务名称 | 旧系统任务同步 |
| 任务组名 | DEFAULT |
| 调用目标字符串 | `legacySystemSyncTask.syncPendingTasks()` |
| cron表达式 | `0 0/10 * * * ?` (每10分钟执行一次) |
| 执行策略 | 立即执行 |
| 是否并发 | 否 |
| 状态 | 正常 |

### 3. cron表达式参考

| 说明 | cron表达式 |
|------|-----------|
| 每5分钟 | `0 0/5 * * * ?` |
| 每10分钟 | `0 0/10 * * * ?` |
| 每30分钟 | `0 0/30 * * * ?` |
| 每小时 | `0 0 * * * ?` |
| 每天凌晨2点 | `0 0 2 * * ?` |

## 五、同步机制说明

### 1. 自动同步流程

```
创建急救转运任务
    ↓
保存到数据库
    ↓
异步调用旧系统接口 (2秒延迟)
    ↓
更新sync_status状态
    ↓
保存返回的ServiceOrdID
```

### 2. 定时同步流程

```
定时任务触发
    ↓
查询未同步/同步失败的任务 (sync_status = 0 or 3)
    ↓
逐个调用旧系统接口 (间隔1秒)
    ↓
更新同步状态
    ↓
记录日志
```

### 3. 同步状态说明

| sync_status | 说明 | 处理方式 |
|------------|------|---------|
| 0 | 未同步 | 等待自动同步或定时任务处理 |
| 1 | 同步中 | 正在调用旧系统接口 |
| 2 | 同步成功 | 已获得ServiceOrdID，不再重复同步 |
| 3 | 同步失败 | 记录错误信息，等待定时任务重试 |

## 六、数据映射关系

### 新系统 -> 旧系统字段映射

| 新系统字段 | 旧系统字段 | 说明 |
|----------|-----------|------|
| taskId | - | 新系统任务ID |
| patientName | ServiceOrdPtName | 患者姓名 |
| patientContact | ServiceOrdCoName | 联系人姓名 |
| patientPhone | ServiceOrdCoPhone | 联系人电话 |
| patientGender | ServiceOrdPtSex | 患者性别 (0=男, 1=女) |
| patientIdCard | ServiceOrdPtIDCard | 患者身份证 |
| patientCondition | ServiceOrdPtCondition | 病情描述 |
| hospitalOutName | ServiceOrdPtOutHosp | 转出医院 |
| hospitalOutDepartment | ServiceOrdPtServices | 转出科室 |
| hospitalOutAddress | ServiceOrdTraStreet | 出发地址 |
| hospitalInName | ServiceOrdPtInHosp | 转入医院 |
| hospitalInDepartment | ServiceOrdPtInServices | 转入科室 |
| hospitalInAddress | ServiceOrdTraEnd | 目的地址 |
| transferDistance | ServiceOrdTraDistance | 转运距离 |
| transferPrice | ServiceOrdTraTxnPrice | 成交价 |
| taskDescription | ServiceOrdTaskRemarks | 任务备注 |
| plannedStartTime | ServiceOrdApptDate | 预约时间 |

### 固定值映射

| 旧系统字段 | 固定值 | 说明 |
|----------|--------|------|
| ServiceOrdClass | JJ | 急救类型 |
| ServiceOrdState | 2 | 正式单 |
| ServiceOrdSource | 10 | 订单来源(新系统) |
| ServiceOrdAreaType | 1 | 服务区域 |
| ServiceOrdType | 1 | 服务类型 |
| OrderLevel | 2 | 查看等级 |

## 七、监控与日志

### 1. 查看同步状态

```sql
-- 查看所有任务的同步状态
SELECT 
    t.task_id,
    t.task_code,
    e.sync_status,
    e.legacy_service_ord_id,
    e.sync_time,
    e.sync_error_msg
FROM sys_task t
LEFT JOIN sys_task_emergency e ON t.task_id = e.task_id
WHERE t.task_type = 'EMERGENCY_TRANSFER'
ORDER BY t.create_time DESC;

-- 统计同步状态
SELECT 
    sync_status,
    CASE sync_status
        WHEN 0 THEN '未同步'
        WHEN 1 THEN '同步中'
        WHEN 2 THEN '同步成功'
        WHEN 3 THEN '同步失败'
    END AS status_name,
    COUNT(*) AS count
FROM sys_task_emergency
GROUP BY sync_status;

-- 查看同步失败的任务
SELECT 
    t.task_id,
    t.task_code,
    e.sync_error_msg,
    e.sync_time
FROM sys_task t
JOIN sys_task_emergency e ON t.task_id = e.task_id
WHERE e.sync_status = 3
ORDER BY e.sync_time DESC;
```

### 2. 日志文件位置

- 应用日志: `logs/sys-info.log`
- 错误日志: `logs/sys-error.log`

关键日志标识:
```
[LegacySystemSyncServiceImpl] 任务同步成功
[LegacySystemSyncServiceImpl] 任务同步失败
[LegacySystemSyncTask] 旧系统任务同步完成
```

## 八、故障排查

### 1. 任务一直未同步 (sync_status = 0)

**可能原因**:
- 自动同步线程异常
- 定时任务未启动
- 配置的 `enabled` 为 false

**解决方案**:
1. 检查配置: `legacy.system.enabled = true`
2. 检查定时任务状态是否为"正常"
3. 手动触发定时任务: 在定时任务列表中点击"执行一次"
4. 查看应用日志是否有异常

### 2. 同步失败 (sync_status = 3)

**可能原因**:
- 旧系统URL配置错误
- 网络不通
- 旧系统接口异常
- 数据验证失败

**解决方案**:
1. 查看 `sync_error_msg` 字段的错误信息
2. 检查旧系统URL是否正确: `legacy.system.base-url`
3. 测试网络连接: `curl http://旧系统地址/admin_save_19.gds`
4. 查看旧系统日志
5. 手动重新同步: 将 `sync_status` 改为 0，等待定时任务重试

### 3. 重复同步

**防止机制**:
- 已同步成功的任务 (sync_status = 2) 不会再次同步
- 有 `legacy_service_ord_id` 的任务会跳过

**手动重新同步方法**:
```sql
-- 重置同步状态（谨慎操作）
UPDATE sys_task_emergency 
SET sync_status = 0, 
    legacy_service_ord_id = NULL,
    sync_error_msg = NULL
WHERE task_id = <任务ID>;
```

## 九、性能优化建议

### 1. 批量同步限制

- 每次定时任务最多同步100个任务
- 每个任务间隔1秒，避免过于频繁请求
- 建议定时任务间隔: 10-30分钟

### 2. 超时配置

根据网络情况调整超时时间:
- 局域网: 10-15秒
- 互联网: 30-60秒

### 3. 监控告警

建议配置以下监控:
- 同步失败率超过20%时告警
- 连续3次同步全部失败时告警
- 未同步任务累积超过50个时告警

## 十、安全注意事项

1. **网络安全**:
   - 使用HTTPS协议 (如旧系统支持)
   - 配置IP白名单
   - 使用VPN或专线连接

2. **数据安全**:
   - 患者信息加密传输
   - 敏感字段脱敏处理
   - 定期清理历史同步日志

3. **权限控制**:
   - 限制旧系统API访问权限
   - 定期更换认证凭证 (如有)

## 十一、联系与支持

如遇到问题，请提供以下信息:
1. 任务ID
2. sync_error_msg 内容
3. 相关日志截图
4. 旧系统返回内容

技术支持: 系统管理员