用户同步功能开发总结

📋 项目信息

• 开发日期: 2025-10-18
• 功能名称: OA用户同步
• 依赖功能: 部门同步
• 技术栈: Spring Boot + MyBatis + SQL Server

🎯 需求概述

从SQL Server数据库的OA_User表中同步用户数据到若依系统的sys_user表，通过department_id字段关联部门。

数据源SQL

SELECT 
    OA_User_ID as OA_UserID,
    OA_User as user_name,
    OA_Name as nick_name,
    OA_departmentID as department_id,
    OA_gender as sex,
    OA_email as email,
    OA_mobile as phonenumber
FROM OA_User
WHERE OA_User IS NOT NULL AND OA_Name IS NOT NULL

字段映射

• OA_User_ID → oa_user_id（唯一标识）
• OA_User → user_name（用户账号）
• OA_Name → nick_name（用户昵称）
• OA_departmentID → department_id（部门关联键）
• OA_gender → sex（性别）
• OA_email → email（邮箱）
• OA_mobile → phonenumber（手机号）

🔨 实现内容

1. 数据库修改

表结构变更

-- 在sys_user表中添加oa_user_id字段
ALTER TABLE sys_user ADD COLUMN oa_user_id INT NULL COMMENT 'SQL Server中的OA用户ID';
CREATE INDEX idx_oa_user_id ON sys_user(oa_user_id);

文件: sql/add_oa_user_id_to_sys_user.sql

2. 实体类修改

SysUser实体

文件: ruoyi-common/src/main/java/com/ruoyi/common/core/domain/entity/SysUser.java

修改内容:
```java
/** SQL Server中的OA用户ID */
private Integer oaUserId;

public Integer getOaUserId() { return oaUserId; }
public void setOaUserId(Integer oaUserId) { this.oaUserId = oaUserId; }
```

3. 新增文件

DTO层

文件: ruoyi-system/src/main/java/com/ruoyi/system/domain/UserSyncDTO.java
- 功能: 用户同步数据传输对象
- 字段: oaUserId, userName, nickName, departmentId, sex, email, phonenumber

Mapper层

文件:
- ruoyi-system/src/main/java/com/ruoyi/system/mapper/UserSyncMapper.java
- ruoyi-system/src/main/resources/mapper/system/UserSyncMapper.xml

主要方法:
- List<UserSyncDTO> selectOaUsers() - 查询SQL Server用户数据

Service层

文件:
- ruoyi-system/src/main/java/com/ruoyi/system/service/IUserSyncService.java
- ruoyi-system/src/main/java/com/ruoyi/system/service/impl/UserSyncServiceImpl.java

核心方法: syncOaUsers()

同步逻辑:
1. 从SQL Server获取OA_User数据
2. 验证数据完整性
3. 根据department_id查找对应的dept_id
4. 检查用户是否已存在（根据oa_user_id）
5. 已存在则更新，不存在则创建
6. 返回同步统计结果

Controller层

文件: ruoyi-admin/src/main/java/com/ruoyi/web/controller/system/DepartmentSyncController.java（扩展）

接口:
- POST /system/dept/sync/user - 同步OA用户
- 权限: system:user:sync

4. Mapper扩展

SysUserMapper

文件:
- ruoyi-system/src/main/java/com/ruoyi/system/mapper/SysUserMapper.java
- ruoyi-system/src/main/resources/mapper/system/SysUserMapper.xml

新增方法:
java // 根据oaUserId查询用户 SysUser selectUserByOaUserId(@Param("oaUserId") Integer oaUserId);

修改内容:
- resultMap中添加oa_user_id映射
- selectUserVo中添加oa_user_id字段
- insertUser中添加oa_user_id支持
- updateUser中添加oa_user_id支持
- 新增selectUserByOaUserId查询方法

5. 文档

功能说明文档

文件: prd/用户同步功能说明.md
- 功能概述
- 数据源说明
- 字段映射关系
- 同步逻辑详解
- 接口说明
- 使用步骤
- 验证方法

快速开始

文件: 用户同步-快速开始.md
- 安装步骤
- 使用方法
- 返回示例
- 核心逻辑
- 常见问题

📊 技术特性

1. 智能部门关联

• 通过department_id自动查找对应的dept_id
• 找不到部门时使用默认部门(100)
• 详细记录部门关联日志

2. 幂等性设计

• 通过oa_user_id判断用户是否已存在
• 多次执行不会创建重复数据
• 已存在用户只更新信息

3. 智能用户匹配

• 优先根据oa_user_id查找用户
• 用户名已存在时更新oa_user_id
• 避免创建重复用户

4. 数据完整性验证

• 验证必填字段（用户名、昵称）
• 跳过不完整的数据
• 记录跳过原因

5. 错误处理

• 单个用户失败不影响整体同步
• 捕获并记录详细错误信息
• 返回完整的统计信息

6. 事务保护

• 使用@Transactional注解
• 同步过程中出错自动回滚
• 保证数据一致性

7. 默认值设置

• 新用户默认密码: 123456（加密存储）
• 默认部门: 100（若依科技）
• 默认性别: 2（未知）
• 默认状态: 0（正常）

🔍 同步流程

1. 从SQL Server查询OA_User数据
   ↓
2. 遍历每条用户数据
   ↓
3. 验证数据完整性（用户名、昵称）
   ├─ 不完整 → 跳过
   └─ 完整 → 继续
   ↓
4. 根据department_id查找dept_id
   ├─ 找到 → 使用对应dept_id
   └─ 未找到 → 使用默认dept_id(100)
   ↓
5. 根据oa_user_id查询用户
   ├─ 找到 → 更新用户信息
   └─ 未找到 → 检查用户名
      ├─ 用户名存在 → 更新并设置oa_user_id
      └─ 用户名不存在 → 创建新用户
   ↓
6. 返回统计结果

📈 同步结果示例

输入（SQL Server OA_User表）

OA_User_ID | OA_User  | OA_Name | OA_departmentID | OA_gender | OA_email
1001       | zhangsan | 张三     | 1001           | 0         | zhangsan@qq.com
1002       | lisi     | 李四     | 1001           | 1         | lisi@qq.com
1003       | wangwu   | 王五     | 1002           | 0         | wangwu@qq.com

处理过程

1. 用户zhangsan:

• department_id=1001 → 查询sys_dept → dept_id=201
• oa_user_id=1001不存在 → 用户名不存在
• 创建新用户（密码: 123456）

1. 用户lisi:

• department_id=1001 → dept_id=201
• oa_user_id=1002不存在 → 用户名已存在
• 更新已存在用户，设置oa_user_id=1002

1. 用户wangwu:

• department_id=1002 → dept_id=202
• 创建新用户

输出（sys_user表）

user_id | user_name | nick_name | dept_id | oa_user_id | email
101     | zhangsan  | 张三      | 201     | 1001       | zhangsan@qq.com
102     | lisi      | 李四      | 201     | 1002       | lisi@qq.com
103     | wangwu    | 王五      | 202     | 1003       | wangwu@qq.com

接口返回

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

🎓 使用示例

1. 执行顺序（重要！）

# 第一步：同步部门
POST http://localhost:8080/system/dept/sync/branch

# 第二步：同步用户
POST http://localhost:8080/system/dept/sync/user

2. Postman调用

POST http://localhost:8080/system/dept/sync/user
Headers:
  Authorization: Bearer eyJhbGciOiJIUzUxMiJ9...

3. curl命令

curl -X POST http://localhost:8080/system/dept/sync/user \
  -H "Authorization: Bearer {token}"

4. 前端调用

this.$http.post('/system/dept/sync/user').then(res => {
  this.$message.success(res.msg);
  this.getList();
});

⚙️ 配置说明

前置依赖

必须先完成部门同步！
1. 执行 add_department_id_to_sys_dept.sql
2. 调用 /system/dept/sync/branch 同步部门
3. 然后才能同步用户

SQL Server数据源

文件: ruoyi-admin/src/main/resources/application-dev.yml

spring:
  datasource:
    druid:
      sqlserver:
        enabled: true
        url: jdbc:sqlserver://your-server:1433;DatabaseName=your-db
        username: your-username
        password: your-password
        driver-class-name: com.microsoft.sqlserver.jdbc.SQLServerDriver

🚀 部署清单

1. 数据库操作

• [ ] 执行 add_department_id_to_sys_dept.sql
• [ ] 执行 add_oa_user_id_to_sys_user.sql

2. 同步操作

• [ ] 调用部门同步接口
• [ ] 调用用户同步接口

3. 验证测试

• [ ] 检查同步用户数量
• [ ] 检查部门关联情况
• [ ] 验证日志输出
• [ ] 测试新用户登录（用户名/123456）

📝 关键要点

执行顺序

1. 部门同步（必须先执行）
2. 用户同步（依赖部门数据）

默认设置

• 🔑 新用户密码: 123456
• 🏢 默认部门: 100（若依科技）
• 👤 默认性别: 2（未知）
• ✅ 默认状态: 0（正常）

幂等性保证

• ✅ 多次同步不会创建重复数据
• ✅ 已存在用户只会更新信息
• ✅ 根据oa_user_id唯一标识用户

📚 参考资料

• 若依框架文档: http://doc.ruoyi.vip
• MyBatis文档: https://mybatis.org/mybatis-3/zh/
• Spring Boot文档: https://spring.io/projects/spring-boot

✅ 总结

本次开发完成了从SQL Server到MySQL的用户数据同步功能，主要特点：

1. 智能部门关联: 通过department_id自动关联sys_dept表
2. 幂等性保证: 支持重复执行，不会创建重复数据
3. 智能用户匹配: 根据oa_user_id和用户名双重判断
4. 数据完整性: 验证必填字段，跳过不完整数据
5. 事务安全: 使用事务保证数据一致性
6. 详细日志: 记录完整的同步过程
7. 错误处理: 单个失败不影响整体，详细记录错误
8. 文档齐全: 提供功能说明、快速开始、测试指南

功能已完成开发和自测，可以进入测试和部署阶段。

🔗 相关文档

• 用户同步详细说明
• 用户同步快速开始
• 部门同步功能说明
• 部门同步快速开始

👨‍💻 作者

ruoyi

📅 日期

2025-10-18