OA数据同步定时任务使用指南

📋 概述

本文档说明如何配置和使用OA数据同步定时任务，实现部门和用户数据的自动同步。

🎯 定时任务列表

系统提供了3个定时任务类，您可以根据需求选择使用：

1. OaSyncTask（推荐）⭐

Bean名称: oaSyncTask
功能: 完整的OA数据同步（部门+用户）
特点:
- ✅ 按正确顺序执行：先部门后用户
- ✅ 一个任务搞定所有同步
- ✅ 智能错误处理：部门失败则跳过用户

可用方法:
- syncOaData() - 完整同步（部门+用户）
- syncDepartmentsOnly() - 仅同步部门
- syncUsersOnly() - 仅同步用户

2. DepartmentSyncTask

Bean名称: departmentSyncTask
功能: 仅同步部门数据
特点: 独立的部门同步任务

可用方法:
- syncDepartments() - 同步部门

3. UserSyncTask

Bean名称: userSyncTask
功能: 仅同步用户数据
特点: 独立的用户同步任务
注意: ⚠️ 必须在部门同步之后执行

可用方法:
- syncUsers() - 同步用户

🚀 快速开始

方式一：使用SQL脚本初始化（推荐）

1. 执行SQL脚本

mysql -u root -p ry-vue < sql/oa_sync_job.sql

这会创建3个定时任务：
1. OA数据同步 - 每天凌晨2点执行（推荐）
2. OA部门同步 - 每天凌晨2点执行
3. OA用户同步 - 每天凌晨3点执行

2. 启用任务

1. 登录若依管理后台
2. 进入 系统管理 → 定时任务
3. 找到"OA数据同步"任务
4. 点击"恢复"按钮启用任务

方式二：手动添加任务

1. 进入定时任务管理

登录若依后台 → 系统管理 → 定时任务 → 新增

2. 配置任务信息

推荐配置（完整同步）:
任务名称: OA数据同步 任务分组: DEFAULT 调用目标: oaSyncTask.syncOaData cron表达式: 0 0 2 * * ? 执行策略: 立即执行 是否并发: 否 状态: 正常

独立部门同步:
任务名称: OA部门同步 任务分组: DEFAULT 调用目标: departmentSyncTask.syncDepartments cron表达式: 0 0 2 * * ? 执行策略: 立即执行 是否并发: 否 状态: 正常

独立用户同步:
任务名称: OA用户同步 任务分组: DEFAULT 调用目标: userSyncTask.syncUsers cron表达式: 0 0 3 * * ? 执行策略: 立即执行 是否并发: 否 状态: 正常

⏰ Cron表达式参考

表达式	说明	推荐场景
0 0 2 * * ?	每天凌晨2点执行	日常同步（推荐）
0 0 3 * * ?	每天凌晨3点执行	用户同步（需在部门后）
0 0 */4 * * ?	每4小时执行一次	频繁同步
0 0/30 * * * ?	每30分钟执行一次	实时同步
0 0 2 * * MON	每周一凌晨2点执行	周同步
0 0 2 1 * ?	每月1号凌晨2点执行	月同步

📊 使用示例

示例1：使用完整同步任务（推荐）

任务配置：
- 调用目标：oaSyncTask.syncOaData
- Cron表达式：0 0 2 * * ?
- 说明：每天凌晨2点自动同步部门和用户

执行流程：
1. 同步部门数据
2. 部门同步成功后，同步用户数据
3. 记录详细日志

示例2：使用独立任务

任务1 - 部门同步：
- 调用目标：departmentSyncTask.syncDepartments
- Cron表达式：0 0 2 * * ?

任务2 - 用户同步：
- 调用目标：userSyncTask.syncUsers  
- Cron表达式：0 0 3 * * ?（必须在部门同步之后）

🔍 监控与日志

查看任务执行日志

1. 在定时任务管理界面查看

• 进入 系统管理 → 定时任务
• 点击任务后的"调度日志"按钮
• 查看执行结果

2. 查看系统日志文件

# 查看同步日志
tail -f ruoyi-admin/logs/sys-info.log | grep -i "OA\|Department\|User"

# 查看错误日志
tail -f ruoyi-admin/logs/sys-error.log

日志示例

完整同步日志

INFO  OaSyncTask - ##########开始执行OA数据同步定时任务##########
INFO  OaSyncTask - 【步骤1/2】开始同步部门数据...
INFO  DepartmentSyncServiceImpl - 从SQL Server获取到 12 条分公司数据
INFO  DepartmentSyncServiceImpl - 创建新分公司: 湛江分公司, ID: 200
INFO  OaSyncTask - 【步骤1/2】部门同步成功: 同步完成！创建分公司: 3, 创建部门: 12
INFO  OaSyncTask - 【步骤2/2】开始同步用户数据...
INFO  UserSyncServiceImpl - 从SQL Server获取到 50 条用户数据
INFO  UserSyncServiceImpl - 创建新用户: 张三 (zhangsan), oaUserId: 1001
INFO  OaSyncTask - 【步骤2/2】用户同步成功: 同步完成！创建用户: 30, 更新用户: 15
INFO  OaSyncTask - ##########OA数据同步定时任务执行完成##########
INFO  OaSyncTask - 总结：部门同步成功，用户同步成功

🔧 高级配置

1. 调整同步频率

根据实际需求修改cron表达式：

高频同步（每小时）:
cron表达式: 0 0 * * * ?

工作时间同步（工作日8-18点，每小时）:
cron表达式: 0 0 8-18 * * MON-FRI

2. 错过执行策略

• 立即执行: 任务错过后立即补执行
• 执行一次: 执行一次后继续按计划
• 放弃执行: 忽略错过的执行

3. 并发控制

建议设置为"禁止并发"，避免同时执行多个同步任务。

❗ 注意事项

⚠️ 重要提示

1. 执行顺序很重要

• 必须先同步部门，再同步用户
• 推荐使用oaSyncTask.syncOaData完整同步

1. 时间间隔设置

• 如果使用独立任务，用户同步至少在部门同步5分钟后

1. 首次使用

• 首次启用前先手动执行一次测试
• 确认SQL Server连接正常

1. 权限配置

• 确保有定时任务管理权限
• 确保有部门和用户同步权限

✅ 最佳实践

1. 推荐使用完整同步任务
   调用目标: oaSyncTask.syncOaData 优点: 自动按顺序执行，无需担心顺序问题

2. 合理设置执行时间
   建议: 凌晨2-3点执行（业务低峰期） 避免: 业务高峰期执行

3. 监控任务执行
   ```

• 定期查看调度日志
• 关注失败记录
• 设置告警通知
  ```

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

🎓 故障排查

Q1: 任务创建后不执行？

检查项:
1. 任务状态是否为"正常"
2. Cron表达式是否正确
3. 调用目标字符串是否正确
4. 查看错误日志

Q2: 用户同步后部门为空？

原因: 部门未同步或同步失败
解决:
1. 检查部门同步任务是否成功
2. 确保用户同步在部门同步之后执行
3. 使用oaSyncTask.syncOaData完整同步

Q3: 任务执行报错？

排查步骤:
1. 查看错误日志
2. 检查SQL Server连接
3. 确认Bean是否注入成功
4. 验证数据库字段是否添加

Q4: 如何立即执行一次？

操作:
1. 进入定时任务列表
2. 找到对应任务
3. 点击"执行一次"按钮

📁 相关文件

定时任务类

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

SQL脚本

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

服务类

• IDepartmentSyncService.java - 部门同步服务
• IUserSyncService.java - 用户同步服务

🔗 相关文档

• 部门同步功能说明
• 用户同步功能说明
• OA数据同步系统使用指南

✅ 总结

定时任务配置完成后：
- ✅ 自动按时同步OA数据
- ✅ 无需手动操作
- ✅ 详细日志记录
- ✅ 错误自动处理

建议使用oaSyncTask.syncOaData完整同步任务，省心省力！

---

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