feat: 实现员工同步任务的WebSocket支持及合同名称锁定功能

- 为EmployeesSyncTask添加WebSocket客户端和服务端支持，实现实时任务进度反馈 - 新增合同名称锁定功能，防止误修改重要合同名称 - 优化SmbFileService的连接异常处理，提高稳定性 - 重构ContractFilesRebuildTasker的任务执行逻辑，改进错误处理 - 更新tasker_mapper.json注册EmployeesSyncTask - 添加相关任务文档和验收报告修复WebSocketClientSession的任务完成状态处理问题改进UITools中任务执行的线程管理优化DepartmentService的findByCode方法返回类型
2025-11-20 16:26:34 +08:00
parent 02afa189f8
commit a784438e97
28 changed files with 983 additions and 329 deletions
--- a/docs/task/EmployeesSyncTask_WebSocket_Design.md
+++ b/docs/task/EmployeesSyncTask_WebSocket_Design.md
@@ -0,0 +1,182 @@
+# 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通信能力，同时保持现有业务逻辑的稳定性和可靠性。