# 旧系统ServiceOrdNo字段同步功能说明

## 一、功能概述

在从旧系统同步转运单（ServiceOrder）到新系统时，除了已有的`ServiceOrdID`（服务单ID）和`DispatchOrdID`（调度单ID），现在还会同步`ServiceOrdNo`（转运单编号）字段，并保存到`sys_task_emergency`表中。

## 二、数据库变更

### 新增字段

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

```sql
-- 旧系统ServiceOrdNo（转运单编号）
ALTER TABLE sys_task_emergency 
ADD COLUMN legacy_service_ord_no VARCHAR(50) NULL COMMENT '旧系统ServiceOrdNo（转运单编号）' AFTER need_resync;

-- 添加索引
ALTER TABLE sys_task_emergency 
ADD INDEX idx_legacy_service_ord_no (legacy_service_ord_no);
```

### 字段说明

| 字段名 | 类型 | 说明 | 示例 |
|--------|------|------|------|
| legacy_service_ord_no | VARCHAR(50) | 旧系统转运单编号 | "123"、"045"等 |

**注意**：`ServiceOrdNo`字段在旧系统中是数字类型，在生成任务编号时会被格式化为3位数字字符串（如 32 → "032"，1 → "001"）。

## 三、代码变更

### 1. 实体类修改

**文件**: `SysTaskEmergency.java`

新增属性：
```java
/** 旧系统ServiceOrdNo（转运单编号） */
private String legacyServiceOrdNo;
```

新增getter/setter方法。

### 2. Mapper XML修改

**文件**: `SysTaskEmergencyMapper.xml`

- 在`resultMap`中添加字段映射
- 在`selectSysTaskEmergencyVo`中添加查询字段
- 在`insertSysTaskEmergency`中添加插入逻辑
- 在`updateSysTaskEmergency`中添加更新逻辑

### 3. Service接口修改

**文件**: `ISysTaskService.java`

修改方法签名，添加`serviceOrdNo`参数：
```java
public int insertTask(TaskCreateVO createVO, String serviceOrderId, 
                     String dispatchOrderId, String serviceOrdNo, 
                     Long userId, String userName, Long deptId, 
                     Date createTime, Date updateTime);
```

### 4. Service实现修改

**文件**: `SysTaskServiceImpl.java`

1. 修改`insertTask`方法签名，添加`serviceOrdNo`参数
2. 修改`saveEmergencyInfo`方法签名，添加`serviceOrdNo`参数
3. 在`saveEmergencyInfo`方法中保存`serviceOrdNo`：

```java
if(serviceOrdNo!=null){
    emergencyInfo.setLegacyServiceOrdNo(serviceOrdNo);
}
```

### 5. 同步服务修改

**文件**: `LegacyTransferSyncServiceImpl.java`

在`syncSingleTransferOrder`方法中：

1. 从旧系统查询结果中提取`ServiceOrdNo`：
```java
String serviceOrdNo = getStringValue(order, "ServiceOrdNo");
```

2. 调用`insertTask`方法时传递`serviceOrdNo`参数：
```java
int result = sysTaskService.insertTask(createTaskVo, serviceOrdID, 
                                      dispatchOrdID, serviceOrdNo, 
                                      taskCreatorId, createUserName, 
                                      deptId, ServiceOrd_CC_Time, ServiceOrd_CC_Time);
```

## 四、数据流转

```
旧系统 ServiceOrder 表
    ↓ (查询)
LegacyTransferSyncServiceImpl
    ↓ (提取)
ServiceOrdNo 字段
    ↓ (传递)
SysTaskService.insertTask()
    ↓ (保存)
SysTaskEmergency.legacy_service_ord_no
```

## 五、使用场景

### 1. 数据追溯
通过`legacy_service_ord_no`字段可以快速在旧系统中定位原始转运单数据。

### 2. 任务编号生成
`ServiceOrdNo`字段用于生成新系统的任务编号（`task_code`），格式为：
```
{ServiceOrdClass}{YYYYMMDD}-{ServiceOrdNo(3位)}
```
例如：`BF20251101-032`

### 3. 数据查询

查询已同步的转运单及其编号：
```sql
SELECT 
    t.task_id,
    t.task_code,
    e.legacy_service_ord_id,
    e.legacy_service_ord_no,
    e.legacy_dispatch_ord_id,
    e.sync_status
FROM sys_task t
JOIN sys_task_emergency e ON t.task_id = e.task_id
WHERE e.legacy_service_ord_no IS NOT NULL
ORDER BY t.create_time DESC;
```

按`ServiceOrdNo`查询特定转运单：
```sql
SELECT 
    t.task_id,
    t.task_code,
    t.task_status,
    e.patient_name,
    e.hospital_out_name,
    e.hospital_in_name
FROM sys_task t
JOIN sys_task_emergency e ON t.task_id = e.task_id
WHERE e.legacy_service_ord_no = '032';
```

## 六、测试验证

### 测试步骤

1. **执行数据库脚本**
   ```bash
   mysql -u用户名 -p数据库名 < sql/add_legacy_service_ord_no.sql
   ```

2. **重启应用**
   确保新代码生效。

3. **触发同步任务**
   - 方式1：手动调用定时任务
   - 方式2：等待自动定时任务执行

4. **验证数据**
   ```sql
   SELECT task_id, legacy_service_ord_id, legacy_service_ord_no
   FROM sys_task_emergency
   WHERE sync_status = 2
   ORDER BY id DESC
   LIMIT 10;
   ```

### 预期结果

- `legacy_service_ord_no`字段应包含从旧系统同步的`ServiceOrdNo`值
- 该字段不为空且格式正确（通常为1-3位数字）
- 与`legacy_service_ord_id`一一对应

## 七、注意事项

1. **字段可空性**：`legacy_service_ord_no`字段允许为NULL，因为：
   - 旧任务可能没有该字段
   - 从新系统创建的任务不会有此字段

2. **数据类型**：虽然`ServiceOrdNo`在旧系统中是数字，但在新系统中使用VARCHAR类型存储，以保持原始格式。

3. **向后兼容**：此修改不影响已存在的数据和功能，只对新同步的转运单有效。

4. **任务编号生成**：`ServiceOrdNo`用于生成任务编号，但如果该字段为空，系统会自动生成新的任务编号。

## 八、相关文件清单

### 数据库脚本
- `sql/add_legacy_service_ord_no.sql` - 添加字段的SQL脚本

### Java文件
- `ruoyi-system/src/main/java/com/ruoyi/system/domain/SysTaskEmergency.java`
- `ruoyi-system/src/main/java/com/ruoyi/system/service/ISysTaskService.java`
- `ruoyi-system/src/main/java/com/ruoyi/system/service/impl/SysTaskServiceImpl.java`
- `ruoyi-system/src/main/java/com/ruoyi/system/service/impl/LegacyTransferSyncServiceImpl.java`

### Mapper文件
- `ruoyi-system/src/main/resources/mapper/system/SysTaskEmergencyMapper.xml`

### 文档
- `旧系统ServiceOrdNo字段同步功能说明.md` - 本文档

## 九、常见问题

### Q1: ServiceOrdNo字段为什么是VARCHAR类型？
**A**: 虽然在旧系统中是数字类型，但使用VARCHAR可以：
- 保留原始格式（如前导零）
- 避免类型转换错误
- 更灵活地处理特殊情况

### Q2: 如果旧系统中ServiceOrdNo为空怎么办？
**A**: 代码中有NULL检查，如果`ServiceOrdNo`为空，该字段在新系统中也为NULL，不影响其他业务。

### Q3: 已同步的历史数据会更新这个字段吗？
**A**: 不会。此功能只对新同步的转运单有效。如需更新历史数据，需要编写专门的数据迁移脚本。

### Q4: 这个字段会影响现有功能吗？
**A**: 不会。这是一个新增字段，不影响任何现有业务逻辑，完全向后兼容。

## 十、后续优化建议

1. **历史数据回填**：可以编写脚本为已同步的历史任务回填`legacy_service_ord_no`字段。

2. **前端展示**：可以在任务详情页面展示该字段，方便用户查看原始转运单编号。

3. **数据校验**：可以添加数据一致性校验，确保`legacy_service_ord_id`和`legacy_service_ord_no`的对应关系正确。

---

**更新日期**: 2024-11-30  
**版本**: v1.0