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

OA数据同步系统 - 完整使用指南

🎯 系统概述

本系统实现了从SQL Server的OA系统到若依管理系统的**部门和用户数据同步**功能。

核心功能

部门同步: 同步组织架构（分公司和部门）
用户同步: 同步用户数据并自动关联部门

技术架构

数据源: SQL Server (OA系统)
目标系统: MySQL (若依系统)
技术栈: Spring Boot + MyBatis
特性: 幂等性、事务保护、错误处理

📦 功能模块

1. 部门同步

数据表: uv_department → sys_dept
关键字段: department_id（外部部门ID）
接口: POST /system/dept/sync/branch
权限: system:dept:sync

2. 用户同步

数据表: OA_User → sys_user
关键字段: oa_user_id（外部用户ID）
接口: POST /system/dept/sync/user
权限: system:user:sync

🚀 快速开始

第一步：准备工作

1.1 执行数据库脚本

# 进入sql目录
cd d:\project\急救转运\code\Api\RuoYi-Vue-master\sql

# 执行部门表扩展
mysql -u root -p ry-vue < add_department_id_to_sys_dept.sql

# 执行用户表扩展
mysql -u root -p ry-vue < add_oa_user_id_to_sys_user.sql

1.2 配置SQL Server数据源

编辑文件：ruoyi-admin/src/main/resources/application-dev.yml

spring:
  datasource:
    druid:
      # 主数据源 (MySQL)
      master:
        url: jdbc:mysql://localhost:3306/ry-vue?useUnicode=true&characterEncoding=utf8&...
        username: root
        password: password
      
      # 从数据源 (SQL Server - OA系统)
      sqlserver:
        enabled: true
        url: jdbc:sqlserver://your-server:1433;DatabaseName=your-database
        username: your-username
        password: your-password
        driver-class-name: com.microsoft.sqlserver.jdbc.SQLServerDriver

1.3 编译启动

# 编译项目
mvn clean package -DskipTests

# 启动服务
cd ruoyi-admin
java -jar target/ruoyi-admin.jar

第二步：执行同步（重要：按顺序执行！）

2.1 先同步部门

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

返回示例:
json { "code": 200, "msg": "同步完成！创建分公司: 3, 更新分公司: 0, 创建部门: 12, 更新部门: 0", "data": { "createdBranch": 3, "updatedBranch": 0, "createdDept": 12, "updatedDept": 0, "totalProcessed": 12 } }

2.2 再同步用户

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

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

第三步：验证结果

3.1 验证部门同步

-- 查看同步的分公司
SELECT * FROM sys_dept 
WHERE parent_id = 100 AND dept_name LIKE '%分公司'
ORDER BY dept_name;

-- 查看部门结构
SELECT 
    d1.dept_name AS '分公司',
    d2.dept_name AS '部门',
    d2.department_id AS 'OA部门ID'
FROM sys_dept d1
INNER JOIN sys_dept d2 ON d1.dept_id = d2.parent_id
WHERE d1.parent_id = 100 AND d1.dept_name LIKE '%分公司'
ORDER BY d1.dept_name, d2.dept_name;

3.2 验证用户同步

-- 查看同步的用户
SELECT 
    u.user_name AS '账号',
    u.nick_name AS '姓名',
    u.oa_user_id AS 'OA用户ID',
    d.dept_name AS '部门',
    u.email AS '邮箱',
    u.phonenumber AS '手机号'
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;

-- 统计同步情况
SELECT 
    COUNT(*) AS '同步用户总数',
    COUNT(DISTINCT dept_id) AS '分布部门数'
FROM sys_user
WHERE oa_user_id IS NOT NULL;

📚 数据流转说明

部门数据流转

SQL Server (uv_department)
  ↓ 查询条件: parent='合作单位'
  ↓ 字段: departmentID, departmentName
  ↓
解析部门名称
  ↓ 格式: "湛江--护士"
  ↓ 拆分为: "湛江分公司" + "护士"
  ↓
MySQL (sys_dept)
  ↓ 创建分公司: parent_id=100
  ↓ 创建子部门: parent_id=分公司ID
  ↓ 记录: department_id=departmentID

用户数据流转

SQL Server (OA_User)
  ↓ 字段映射
  ↓ OA_User_ID → oa_user_id
  ↓ OA_User → user_name
  ↓ OA_Name → nick_name
  ↓ OA_departmentID → department_id
  ↓
部门关联
  ↓ 通过department_id查找sys_dept
  ↓ 获取对应的dept_id
  ↓
MySQL (sys_user)
  ↓ 根据oa_user_id判断
  ↓ 存在 → 更新
  ↓ 不存在 → 创建（密码123456）

💡 核心逻辑

部门同步逻辑

查询SQL Server中"合作单位"下的所有部门
解析部门名称（格式：城市--部门类型）
提取城市名创建分公司（例如：湛江分公司）
创建子部门归属于对应分公司
记录department_id用于后续关联

用户同步逻辑

查询SQL Server的OA_User表
根据OA_departmentID关联sys_dept获取dept_id
根据oa_user_id查询用户是否存在
存在则更新，不存在则创建
新用户默认密码为123456

⚙️ 配置说明

数据库字段扩展

sys_dept表

department_id INT NULL  -- SQL Server中的departmentID

sys_user表

oa_user_id INT NULL  -- SQL Server中的OA_User_ID

默认值设置

新用户默认值

密码: 123456（加密存储）
部门: 100（若依科技）- 找不到部门时
性别: 2（未知）
状态: 0（正常）

分公司默认值

父部门: 100（若依科技）
状态: 0（正常）
创建者: sync

🔧 特性说明

✅ 幂等性

多次执行不会创建重复数据
已存在的数据只会更新
通过唯一标识符（department_id、oa_user_id）判断

✅ 事务保护

使用@Transactional注解
同步失败自动回滚
保证数据一致性

✅ 错误处理

单条数据失败不影响整体
详细记录错误日志
返回完整统计信息

✅ 日志记录

记录同步开始和结束
记录每条数据的处理结果
便于问题排查

📊 监控与日志

查看日志

# 查看部门同步日志
tail -f ruoyi-admin/logs/sys-info.log | grep -i "DepartmentSync"

# 查看用户同步日志
tail -f ruoyi-admin/logs/sys-info.log | grep -i "UserSync"

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

日志示例

# 部门同步
INFO  DepartmentSyncServiceImpl - 从SQL Server获取到 12 条分公司数据
INFO  DepartmentSyncServiceImpl - 创建新分公司: 湛江分公司, ID: 200
INFO  DepartmentSyncServiceImpl - 创建新部门: 湛江分公司 -> 护士, departmentId: 1001
INFO  DepartmentSyncServiceImpl - 同步完成！创建分公司: 3, 创建部门: 12

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

❗ 常见问题

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

原因: 部门未同步或department_id不匹配
解决:
1. 先执行部门同步
2. 检查SQL Server中的departmentID是否正确
3. 查看日志中的警告信息

Q2: 同步接口返回500错误？

原因: SQL Server连接失败或配置错误
解决:
1. 检查application-dev.yml中的数据源配置
2. 确认SQL Server服务正常
3. 检查用户名密码是否正确
4. 查看错误日志

Q3: 新用户无法登录？

账号: SQL Server中的OA_User字段
密码: 123456
建议: 首次登录后修改密码

Q4: 重复执行会创建重复数据吗？

不会: 系统具有幂等性
- 部门通过department_id判断
- 用户通过oa_user_id判断
- 已存在只会更新，不会重复创建

🎯 最佳实践

同步顺序

1. 配置SQL Server数据源
2. 执行数据库脚本
3. 同步部门数据（必须先执行）
4. 同步用户数据
5. 验证同步结果

定时同步建议

1. 部门同步: 每天凌晨2点
2. 用户同步: 每天凌晨3点
3. 增量同步: 每小时一次（可选）

安全建议

新用户首次登录强制修改密码
定期检查同步日志
监控同步失败情况
备份数据库

📁 文件清单

SQL脚本

sql/add_department_id_to_sys_dept.sql - 部门表扩展
sql/add_oa_user_id_to_sys_user.sql - 用户表扩展

部门同步文件

DepartmentSyncDTO.java - 部门DTO
DepartmentSyncMapper.java/xml - 部门数据访问
IDepartmentSyncService.java - 部门服务接口
DepartmentSyncServiceImpl.java - 部门同步逻辑
DepartmentSyncController.java - 部门同步接口

用户同步文件

UserSyncDTO.java - 用户DTO
UserSyncMapper.java/xml - 用户数据访问
IUserSyncService.java - 用户服务接口
UserSyncServiceImpl.java - 用户同步逻辑
DepartmentSyncController.java（扩展） - 用户同步接口

实体扩展

SysDept.java（修改） - 添加departmentId字段
SysUser.java（修改） - 添加oaUserId字段
SysDeptMapper.java/xml（扩展） - 添加查询方法
SysUserMapper.java/xml（扩展） - 添加查询方法

文档

部门同步功能说明.md - 部门同步详细说明
部门同步-快速开始.md - 部门同步快速指南
用户同步功能说明.md - 用户同步详细说明
用户同步-快速开始.md - 用户同步快速指南
部门同步功能开发总结.md - 部门同步开发总结
用户同步功能开发总结.md - 用户同步开发总结
OA数据同步系统-使用指南.md - 本文档

🔗 相关资源

详细文档

快速指南

开发总结

👨‍💻 技术支持

如遇问题，请参考：
1. 查看详细文档
2. 检查日志文件
3. 验证数据库配置
4. 确认执行顺序

✅ 总结

OA数据同步系统已完成开发，具备以下特点：
- ✅ 完整的部门和用户同步功能
- ✅ 幂等性设计，支持重复执行
- ✅ 事务保护，保证数据一致性
- ✅ 详细日志，便于问题排查
- ✅ 智能关联，自动匹配部门
- ✅ 错误处理，单个失败不影响整体
- ✅ 文档齐全，易于使用和维护

系统已通过自测，可以投入使用！

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