用户同步功能 - 快速开始

一、功能说明

从SQL Server的OA_User表同步用户数据到若依系统，通过department_id自动关联部门。

二、前置条件

⚠️ 必须先完成部门同步！ 用户同步依赖部门数据。

三、安装步骤

1️⃣ 执行数据库脚本

# 1. 部门表添加字段（如果未执行）
mysql -u root -p ry-vue < sql/add_department_id_to_sys_dept.sql

# 2. 用户表添加字段
mysql -u root -p ry-vue < sql/add_oa_user_id_to_sys_user.sql

2️⃣ 编译项目

mvn clean package -DskipTests

3️⃣ 启动服务

cd ruoyi-admin
java -jar target/ruoyi-admin.jar

四、使用方法

⚠️ 重要：必须按顺序执行

第一步：同步部门

POST http://localhost:8080/system/dept/sync/branch
Headers:
  Authorization: Bearer {你的token}

第二步：同步用户

POST http://localhost:8080/system/dept/sync/user
Headers:
  Authorization: Bearer {你的token}

五、返回示例

{
  "code": 200,
  "msg": "同步完成！创建用户: 15, 更新用户: 5, 跳过: 2, 失败: 0",
  "data": {
    "created": 15,
    "updated": 5,
    "skipped": 2,
    "error": 0,
    "totalProcessed": 22
  }
}

六、验证结果

-- 查看同步的用户
SELECT 
    u.user_name,
    u.nick_name,
    u.oa_user_id,
    d.dept_name,
    u.email,
    u.phonenumber
FROM sys_user u
LEFT JOIN sys_dept d ON u.dept_id = d.dept_id
WHERE u.oa_user_id IS NOT NULL
ORDER BY u.create_time DESC;

七、核心逻辑

部门关联

OA_departmentID → 查询sys_dept.department_id → 获取dept_id

用户处理

1. 根据oa_user_id查询
   ├─ 存在 → 更新用户信息
   └─ 不存在
      ├─ 用户名存在 → 更新并设置oa_user_id
      └─ 用户名不存在 → 创建新用户（密码123456）

八、默认值说明

新创建用户的默认设置：
- 🔑 密码: 123456
- 🏢 部门: 100（若依科技）- 如果找不到对应部门
- 👤 性别: 2（未知）
- ✅ 状态: 0（正常）

九、核心文件清单

SQL脚本

sql/add_oa_user_id_to_sys_user.sql - 添加字段

Java文件

SysUser.java（修改） - 添加oaUserId字段
UserSyncDTO.java - 用户数据传输对象
UserSyncMapper.java + XML - 查询SQL Server
SysUserMapper.java/XML（扩展） - 扩展查询方法
IUserSyncService.java - 服务接口
UserSyncServiceImpl.java - 核心同步逻辑
DepartmentSyncController.java（扩展） - 添加接口

文档

prd/用户同步功能说明.md - 详细说明

十、常见问题

❌ 用户部门为空？

原因: 部门未同步或department_id不匹配
解决: 先执行部门同步

❌ 用户名重复？

处理: 自动更新已存在用户的oa_user_id，不会报错

❓ 新用户如何登录？

账号: OA_User字段值
密码: 123456
建议: 首次登录后修改密码

十一、注意事项

✅ 执行顺序很重要
1. 先同步部门
2. 再同步用户

✅ 幂等性保证
- 多次同步不会创建重复数据
- 已存在用户只会更新信息

✅ 权限要求
- 部门同步: system:dept:sync
- 用户同步: system:user:sync

十二、监控与日志

查看日志

tail -f ruoyi-admin/logs/sys-info.log | grep -i "UserSync"

日志示例

INFO  UserSyncServiceImpl - 从SQL Server获取到 50 条用户数据
INFO  UserSyncServiceImpl - 创建新用户: 张三 (zhangsan), oaUserId: 1001, deptId: 201
INFO  UserSyncServiceImpl - 更新用户: 李四 (lisi), oaUserId: 1002
WARN  UserSyncServiceImpl - 未找到对应的部门: departmentId=9999, 用户: test
INFO  UserSyncServiceImpl - 同步完成！创建用户: 30, 更新用户: 15, 跳过: 3, 失败: 2

十三、下一步

前端集成

在用户管理页面添加"同步"按钮：
javascript syncUsers() { this.$confirm('确认同步OA用户数据吗？', '提示', { type: 'warning' }).then(() => { this.$http.post('/system/dept/sync/user').then(res => { this.$message.success(res.msg); this.getList(); }); }); }

定时任务

配置每天自动同步：
- 任务名称: OA用户同步
- 调用目标: userSyncTask.execute
- cron表达式: 0 0 3 * * ? (每天凌晨3点)