contract-manager/docs/task/EmployeesSyncTask_WebSocket_Design.md

# EmployeesSyncTask WebSocket集成设计方案

## 1. 当前状态分析

### 客户端现状
- **文件位置**: `client/src/main/java/com/ecep/contract/task/EmployeesSyncTask.java`
- **代码规模**: 13行，基础空实现
- **继承关系**: 继承`Tasker<Object>`
- **问题**: 缺少`WebSocketClientTasker`接口实现，无法与服务器通信

### 服务器端现状
- **文件位置**: `server/src/main/java/com/ecep/contract/cloud/u8/EmployeesSyncTask.java`
- **代码规模**: 159行，完整的U8系统员工同步逻辑
- **继承关系**: 继承`Tasker<Object>`
- **问题**: 缺少`WebSocketServerTasker`接口实现，无法支持WebSocket通信
- **未注册**: 未在`tasker_mapper.json`中注册

## 2. WebSocket集成设计目标

### 核心目标
1. **统一任务模式**: 客户端调用服务器端任务执行
2. **实时状态同步**: 通过WebSocket实时推送任务进度和消息
3. **保持业务逻辑**: 服务器端业务逻辑保持不变，仅添加通信支持
4. **遵循项目规范**: 严格按照项目现有的WebSocket通信规范

### 设计原则
- **最小修改**: 服务器端现有业务逻辑保持不变
- **接口一致性**: 遵循项目现有的`WebSocketClientTasker`和`WebSocketServerTasker`接口规范
- **任务名称统一**: 使用相同的任务名称确保客户端能够调用服务器端任务
- **向后兼容**: 确保现有调用方式能够平滑升级

## 3. 客户端设计

### 接口实现要求
```java
public class EmployeesSyncTask extends Tasker<Object> implements WebSocketClientTasker {
    // 1. 实现WebSocketClientTasker接口方法
    // 2. 实现getTaskName()方法，返回"EmployeesSyncTask"
    // 3. 实现消息和进度更新处理
    // 4. 集成现有的任务监控和UI反馈机制
}
```

### 功能特性
- **远程任务调用**: 通过WebSocket调用服务器端EmployeesSyncTask
- **进度实时反馈**: 接收服务器端推送的进度更新并更新UI
- **消息日志显示**: 接收服务器端消息并在客户端显示
- **任务状态管理**: 支持任务取消、暂停等状态控制
- **错误处理**: 处理网络异常、任务执行异常等

### UI集成点
- **任务对话框**: 使用项目现有的`UITools.showTaskDialogAndWait()`方法
- **进度显示**: 更新任务进度条和百分比
- **日志输出**: 在任务对话框中显示实时日志消息

## 4. 服务器端设计

### 接口实现要求
```java
public class EmployeesSyncTask extends Tasker<Object> implements WebSocketServerTasker {
    // 1. 实现WebSocketServerTasker接口（继承自Callable<Object>）
    // 2. 保持现有的execute()业务逻辑不变
    // 3. 自动获得WebSocket消息推送能力
}
```

### 保持的业务逻辑
- **U8数据同步**: 保持现有的U8系统Person数据表读取逻辑
- **员工信息映射**: 保持现有的员工和部门信息映射逻辑
- **数据库操作**: 保持现有的员工信息CRUD操作
- **进度管理**: 保持现有的进度计算和更新逻辑

### 新增的通信能力
- **WebSocket支持**: 通过`WebSocketServerTasker`接口获得WebSocket通信能力
- **消息推送**: 自动将`holder.debug/info/warn`消息推送到客户端
- **进度推送**: 自动将进度更新推送到客户端
- **状态同步**: 支持客户端的任务状态控制（如取消）

## 5. 配置注册设计

### 注册文件位置
`server/src/main/resources/tasker_mapper.json`

### 注册内容
```json
{
  "taskers": {
    "EmployeesSyncTask": "com.ecep.contract.cloud.u8.EmployeesSyncTask"
  }
}
```

### 注册原则
- **任务名称**: 使用类名`EmployeesSyncTask`作为任务名称
- **完全限定名**: 使用完整的Java类路径
- **唯一性**: 确保任务名称在整个项目中唯一

## 6. 通信流程设计

### 完整调用流程
1. **UI触发**: 用户在客户端界面触发员工同步任务
2. **客户端创建**: 客户端创建`EmployeesSyncTask`实例
3. **WebSocket连接**: 建立客户端到服务器的WebSocket连接
4. **任务提交**: 客户端通过WebSocket提交任务请求
5. **服务器执行**: 服务器端创建`EmployeesSyncTask`实例并执行
6. **实时推送**: 服务器端实时推送执行进度和消息到客户端
7. **UI更新**: 客户端接收推送消息并更新UI显示
8. **任务完成**: 任务完成后返回执行结果

### 消息类型
- **进度更新**: `{type: "progress", current: 10, total: 100}`
- **日志消息**: `{type: "message", level: "info", message: "正在处理员工张三"}`
- **任务状态**: `{type: "status", status: "running|cancelled|completed"}`
- **错误信息**: `{type: "error", message: "执行出错信息"}`

## 7. 技术实现要点

### 客户端实现要点
1. **接口导入**: 导入`com.ecep.contract.WebSocketClientTasker`
2. **方法实现**: 实现`getTaskName()`、`updateTitle()`等接口方法
3. **UI集成**: 集成项目现有的任务监控和UI反馈机制
4. **异常处理**: 处理网络异常、任务执行异常等边界情况

### 服务器端实现要点
1. **接口导入**: 导入`com.ecep.contract.service.tasker.WebSocketServerTasker`
2. **继承关系**: 继承`Tasker<Object>`并实现`WebSocketServerTasker`
3. **业务保持**: 保持现有的execute()方法业务逻辑不变
4. **配置注册**: 在tasker_mapper.json中注册任务

### 配置部署要点
1. **配置更新**: 在tasker_mapper.json中添加EmployeesSyncTask注册
2. **重启服务**: 配置修改后需要重启服务器服务
3. **通信测试**: 验证客户端-服务器端WebSocket通信正常

## 8. 验收标准

### 功能验收
- [ ] 客户端能够成功调用服务器端EmployeesSyncTask
- [ ] 任务执行进度能够实时同步到客户端UI
- [ ] 任务执行日志能够实时显示在客户端界面
- [ ] 任务取消功能能够正常工作
- [ ] 网络异常时能够进行适当处理

### 技术验收
- [ ] 客户端代码编译通过
- [ ] 服务器端代码编译通过
- [ ] 服务器端能够正常启动和注册任务
- [ ] WebSocket连接建立和通信正常
- [ ] 数据传输格式符合项目规范

### 质量验收
- [ ] 代码风格符合项目规范
- [ ] 异常处理机制完善
- [ ] 日志输出清晰明确
- [ ] 用户体验流畅自然
- [ ] 性能表现良好

## 9. 风险评估与缓解

### 技术风险
- **WebSocket连接稳定性**: 通过异常处理和重连机制缓解
- **消息序列化兼容性**: 严格按照项目现有格式实现
- **任务执行超时**: 通过合理的超时设置和进度更新缓解

### 业务风险
- **数据一致性**: 保持现有业务逻辑，确保数据处理正确性
- **性能影响**: WebSocket通信对现有性能影响最小化
- **用户体验**: 确保升级后的用户体验不下降

## 10. 后续扩展建议

### 功能扩展
- **批量任务支持**: 支持同时执行多个员工同步任务
- **任务历史记录**: 保存任务执行历史和结果统计
- **高级筛选**: 支持按部门、状态等条件筛选同步范围

### 技术优化
- **连接池优化**: 优化WebSocket连接池管理
- **消息压缩**: 对大量日志消息进行压缩传输
- **缓存机制**: 对频繁查询的数据进行缓存优化

这个设计方案确保了EmployeesSyncTask能够顺利集成WebSocket通信能力，同时保持现有业务逻辑的稳定性和可靠性。