部门同步功能说明文档

功能概述

本功能用于从SQL Server数据库同步分公司和部门数据到若依系统的sys_dept表中。

数据源

从SQL Server数据库的uv_department视图中获取"合作单位"下的所有分公司数据。

SQL查询

SELECT b.departmentID, b.departmentName 
FROM uv_department a 
INNER JOIN uv_department b ON a.departmentID = b.parentID 
WHERE a.departmentName = '合作单位'

数据处理规则

1. 部门名称解析

SQL Server中的部门名称格式为：城市--部门类型

示例：
- 湛江--护士
- 湛江--车队
- 湛江--客服
- 湛江--办公室

2. 同步逻辑

解析部门名称：将湛江--护士解析为：

分公司名称：湛江分公司
子部门名称：护士

创建/更新分公司：

父节点：若依科技（dept_id=100）
检查是否已存在同名分公司
不存在则创建新分公司
存在则复用该分公司

创建/更新子部门：

父节点：对应的分公司
记录department_id字段（SQL Server中的departmentID）
检查是否已存在（根据department_id和parent_id）
不存在则创建新部门
存在则更新部门信息

数据库修改

1. 表结构变更

在sys_dept表中新增字段：
sql ALTER TABLE sys_dept ADD COLUMN department_id INT NULL COMMENT 'SQL Server中的部门ID'; CREATE INDEX idx_department_id ON sys_dept(department_id);

2. 实体类变更

SysDept类新增字段：
- private Integer departmentId; - SQL Server中的部门ID

接口说明

同步接口

URL: POST /system/dept/sync/branch
权限: system:dept:sync
返回数据:
json { "code": 200, "msg": "同步完成！创建分公司: 3, 更新分公司: 0, 创建部门: 12, 更新部门: 0", "data": { "createdBranch": 3, "updatedBranch": 0, "createdDept": 12, "updatedDept": 0, "totalProcessed": 12 } }

使用步骤

1. 执行数据库脚本

# 添加department_id字段
mysql -u root -p your_database < sql/add_department_id_to_sys_dept.sql

# 添加菜单权限（可选）
mysql -u root -p your_database < sql/dept_sync_menu.sql

2. 重启后端服务

cd ruoyi-admin
mvn clean package
java -jar target/ruoyi-admin.jar

3. 调用同步接口

使用Postman或其他工具调用：
POST http://localhost:8080/system/dept/sync/branch Headers: Authorization: Bearer {token}

或在前端部门管理页面添加"同步"按钮。

同步示例

输入数据（SQL Server）

departmentID | departmentName
1001        | 湛江--护士
1002        | 湛江--车队
1003        | 湛江--客服
1004        | 湛江--办公室
2001        | 广州--护士
2002        | 广州--车队

输出结果（sys_dept表）

dept_id | parent_id | dept_name    | ancestors    | department_id
200     | 100       | 湛江分公司    | 0,100        | NULL
201     | 200       | 护士         | 0,100,200    | 1001
202     | 200       | 车队         | 0,100,200    | 1002
203     | 200       | 客服         | 0,100,200    | 1003
204     | 200       | 办公室       | 0,100,200    | 1004
210     | 100       | 广州分公司    | 0,100        | NULL
211     | 210       | 护士         | 0,100,210    | 2001
212     | 210       | 车队         | 0,100,210    | 2002

核心代码文件

后端

DepartmentSyncDTO.java - 部门同步DTO
DepartmentSyncMapper.java - 部门同步Mapper接口
DepartmentSyncMapper.xml - 部门同步Mapper XML
IDepartmentSyncService.java - 部门同步Service接口
DepartmentSyncServiceImpl.java - 部门同步Service实现
DepartmentSyncController.java - 部门同步Controller
SysDept.java - 部门实体（添加departmentId字段）
SysDeptMapper.java - 部门Mapper（添加新查询方法）
SysDeptMapper.xml - 部门Mapper XML（添加新SQL）

数据库脚本

sql/add_department_id_to_sys_dept.sql - 添加字段
sql/dept_sync_menu.sql - 添加菜单权限

注意事项

事务处理：同步操作使用@Transactional注解，确保数据一致性
幂等性：多次执行同步操作不会重复创建数据
department_id唯一性：通过department_id字段避免重复同步
日志记录：详细记录同步过程，便于排查问题
权限控制：需要system:dept:sync权限才能执行同步

扩展说明

如果需要定时同步

可以在ruoyi-quartz模块中添加定时任务：

@Component("departmentSyncTask")
public class DepartmentSyncTask {
    @Autowired
    private IDepartmentSyncService departmentSyncService;
    
    public void execute() {
        departmentSyncService.syncBranchDepartments();
    }
}

在系统管理->定时任务中配置：
- 任务名称：分公司同步
- 调用目标字符串：departmentSyncTask.execute
- cron表达式：0 0 2 * * ?（每天凌晨2点执行）

常见问题

Q1: 同步后部门层级不对？

A: 检查ancestors字段是否正确，格式应为0,100,{分公司ID}

Q2: 重复执行同步会创建重复数据吗？

A: 不会，系统会根据department_id和部门名称判断是否已存在

Q3: 如何处理部门名称变更？

A: 系统会根据department_id更新部门名称

Q4: SQL Server连接失败怎么办？

A: 检查application-dev.yml中的sqlserver数据源配置

作者

ruoyi

日期

2025-10-18