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

## 📋 概述

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

## 🎯 定时任务列表

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

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

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

### 2. DepartmentSyncTask
**Bean名称**: `departmentSyncTask`
**功能**: 仅同步部门数据
**特点**: 独立的部门同步任务

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

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

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

## 🚀 快速开始

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

#### 1. 执行SQL脚本
```bash
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. 查看系统日志文件
```bash
# 查看同步日志
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`完整同步

2. **时间间隔设置**
   - 如果使用独立任务，用户同步至少在部门同步5分钟后

3. **首次使用**
   - 首次启用前先手动执行一次测试
   - 确认SQL Server连接正常

4. **权限配置**
   - 确保有定时任务管理权限
   - 确保有部门和用户同步权限

### ✅ 最佳实践

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

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

3. **监控任务执行**
   ```
   - 定期查看调度日志
   - 关注失败记录
   - 设置告警通知
   ```

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

## 🎓 故障排查

### 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` - 用户同步服务

## 🔗 相关文档

- [部门同步功能说明](../prd/部门同步功能说明.md)
- [用户同步功能说明](../prd/用户同步功能说明.md)
- [OA数据同步系统使用指南](../OA数据同步系统-使用指南.md)

## ✅ 总结

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

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

---

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