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. 客户端设计

接口实现要求

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

功能特性

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

UI集成点

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

4. 服务器端设计

接口实现要求

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

注册内容

{
  "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通信能力，同时保持现有业务逻辑的稳定性和可靠性。