966120
编辑 | blame | 历史 | 原始文档

OA数据同步定时任务开发总结

📋 项目信息

  • 开发日期: 2025-10-18
  • 功能名称: OA数据同步定时任务
  • 模块: ruoyi-quartz
  • 依赖功能: 部门同步服务、用户同步服务

🎯 需求概述

在 ruoyi-quartz 模块中实现定时任务，自动同步OA系统的部门和用户数据，确保按正确顺序执行（先部门后用户）。

🔨 实现内容

1. 定时任务类

DepartmentSyncTask（部门同步任务）

文件: ruoyi-quartz/src/main/java/com/ruoyi/quartz/task/DepartmentSyncTask.java

功能:
- 定时同步OA部门数据到sys_dept表
- 独立的部门同步任务

可用方法:
java public void syncDepartments() // 同步部门 public void syncDepartments(String params) // 带参数同步

调用目标:
departmentSyncTask.syncDepartments

UserSyncTask（用户同步任务）

文件: ruoyi-quartz/src/main/java/com/ruoyi/quartz/task/UserSyncTask.java

功能:
- 定时同步OA用户数据到sys_user表
- 独立的用户同步任务
- ⚠️ 必须在部门同步之后执行

可用方法:
java public void syncUsers() // 同步用户 public void syncUsers(String params) // 带参数同步

调用目标:
userSyncTask.syncUsers

OaSyncTask（完整同步任务）⭐ 推荐

文件: ruoyi-quartz/src/main/java/com/ruoyi/quartz/task/OaSyncTask.java

功能:
- 完整的OA数据同步（部门+用户）
- 自动按顺序执行：先部门后用户
- 智能错误处理：部门失败则跳过用户

可用方法:
java public void syncOaData() // 完整同步（部门+用户） public void syncOaData(String params) // 带参数同步 public void syncDepartmentsOnly() // 仅同步部门 public void syncUsersOnly() // 仅同步用户

调用目标:
oaSyncTask.syncOaData // 推荐使用 oaSyncTask.syncDepartmentsOnly oaSyncTask.syncUsersOnly

2. 数据库初始化脚本

文件: sql/oa_sync_job.sql

内容:
创建3个定时任务记录：
1. OA数据同步（完整同步，推荐）
2. OA部门同步（独立任务）
3. OA用户同步（独立任务）

执行方式:
bash mysql -u root -p ry-vue < sql/oa_sync_job.sql

3. 使用文档

文件: OA数据同步定时任务使用指南.md

内容:
- 定时任务列表说明
- 快速开始指南
- Cron表达式参考
- 使用示例
- 监控与日志
- 故障排查
- 最佳实践

📊 技术特性

1. 智能顺序执行

OaSyncTask.syncOaData():
1. 执行部门同步
2. 检查部门同步结果
3. 成功则执行用户同步
4. 失败则跳过用户同步并记录

2. 详细日志记录

INFO  OaSyncTask - ##########开始执行OA数据同步定时任务##########
INFO  OaSyncTask - 【步骤1/2】开始同步部门数据...
INFO  OaSyncTask - 【步骤1/2】部门同步成功: ...
INFO  OaSyncTask - 【步骤2/2】开始同步用户数据...
INFO  OaSyncTask - 【步骤2/2】用户同步成功: ...
INFO  OaSyncTask - ##########OA数据同步定时任务执行完成##########
INFO  OaSyncTask - 总结：部门同步成功，用户同步成功

3. 错误处理

  • 捕获并记录异常
  • 部门失败时跳过用户同步
  • 不影响定时任务调度

4. 灵活配置

  • 支持独立任务（部门/用户单独执行）
  • 支持组合任务（一次性执行）
  • 支持带参数调用（预留扩展）

🚀 使用方式

方式一：执行SQL脚本（推荐）

# 1. 执行初始化脚本
mysql -u root -p ry-vue < sql/oa_sync_job.sql

# 2. 登录后台启用任务
系统管理 → 定时任务 → 找到"OA数据同步" → 恢复

方式二：手动添加任务

进入：系统管理 → 定时任务 → 新增

配置（推荐）:
- 任务名称: OA数据同步
- 调用目标: oaSyncTask.syncOaData
- Cron表达式: 0 0 2 * * ?
- 状态: 正常

⏰ Cron表达式示例

表达式 说明
0 0 2 * * ? 每天凌晨2点执行
0 0 3 * * ? 每天凌晨3点执行
0 0 */4 * * ? 每4小时执行一次
0 0/30 * * * ? 每30分钟执行一次

📁 文件清单

Java文件（ruoyi-quartz模块）

  • DepartmentSyncTask.java - 部门同步任务
  • UserSyncTask.java - 用户同步任务
  • OaSyncTask.java - 完整同步任务（推荐）

SQL脚本

  • sql/oa_sync_job.sql - 定时任务初始化脚本

文档

  • OA数据同步定时任务使用指南.md - 使用说明

🔍 日志示例

成功执行日志

2025-10-18 02:00:00 INFO  OaSyncTask - ##########开始执行OA数据同步定时任务##########
2025-10-18 02:00:00 INFO  OaSyncTask - 【步骤1/2】开始同步部门数据...
2025-10-18 02:00:05 INFO  DepartmentSyncServiceImpl - 从SQL Server获取到 12 条分公司数据
2025-10-18 02:00:10 INFO  OaSyncTask - 【步骤1/2】部门同步成功: 同步完成！创建分公司: 3, 创建部门: 12
2025-10-18 02:00:10 INFO  OaSyncTask - 【步骤2/2】开始同步用户数据...
2025-10-18 02:00:15 INFO  UserSyncServiceImpl - 从SQL Server获取到 50 条用户数据
2025-10-18 02:00:20 INFO  OaSyncTask - 【步骤2/2】用户同步成功: 同步完成！创建用户: 30, 更新用户: 15
2025-10-18 02:00:20 INFO  OaSyncTask - ##########OA数据同步定时任务执行完成##########
2025-10-18 02:00:20 INFO  OaSyncTask - 总结：部门同步成功，用户同步成功

部分失败日志

2025-10-18 02:00:00 INFO  OaSyncTask - ##########开始执行OA数据同步定时任务##########
2025-10-18 02:00:00 INFO  OaSyncTask - 【步骤1/2】开始同步部门数据...
2025-10-18 02:00:01 ERROR OaSyncTask - 【步骤1/2】部门同步失败: SQL Server连接失败
2025-10-18 02:00:01 ERROR OaSyncTask - 由于部门同步失败，跳过用户同步
2025-10-18 02:00:01 ERROR OaSyncTask - ##########OA数据同步定时任务执行失败##########

⚙️ 配置说明

Bean注解

所有任务类都使用 @Component 注解，Spring容器会自动注册：
- @Component("departmentSyncTask")
- @Component("userSyncTask")
- @Component("oaSyncTask")

服务依赖注入

@Autowired
private IDepartmentSyncService departmentSyncService;

@Autowired
private IUserSyncService userSyncService;

💡 最佳实践

1. 推荐使用完整同步任务

调用目标: oaSyncTask.syncOaData
优点: 
- 自动按顺序执行
- 错误处理完善
- 日志清晰

2. 合理设置执行时间

推荐: 凌晨2-3点（业务低峰期）
避免: 业务高峰期

3. 测试后再启用

1. 创建任务时设置为"暂停"
2. 点击"执行一次"测试
3. 确认无误后启用

4. 定期检查日志

- 查看调度日志
- 关注失败记录
- 监控同步数据量

❗ 注意事项

⚠️ 重要提示

  1. 执行顺序
  • 必须先部门后用户
  • 推荐使用 oaSyncTask.syncOaData
  1. 时间间隔
  • 独立任务：用户至少在部门5分钟后
  • 完整任务：自动处理
  1. 首次使用
  • 先手动执行测试
  • 确认SQL Server连接正常
  1. 权限要求
  • 定时任务管理权限
  • 部门和用户同步权限

🔗 相关文档

同步功能文档

快速指南

定时任务文档

✅ 总结

OA数据同步定时任务已完成开发，主要特点：

  1. 完整功能 - 提供3种任务类型，满足不同需求
  2. 智能执行 - 自动按顺序同步，错误处理完善
  3. 详细日志 - 清晰记录每个步骤的执行情况
  4. 易于使用 - SQL脚本一键初始化，文档齐全
  5. 灵活配置 - 支持独立和组合执行方式
  6. 生产就绪 - 经过测试，可直接投入使用

推荐配置:
- 任务：OA数据同步（oaSyncTask.syncOaData）
- 时间：每天凌晨2点（0 0 2 * * ?）
- 状态：启用

系统已完成开发和测试，可以投入生产使用！

版本: 1.0.0
日期: 2025-10-18
作者: ruoyi