# 部门同步功能说明文档

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

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

### SQL查询
```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. 同步逻辑
1. **解析部门名称**：将`湛江--护士`解析为：
   - 分公司名称：`湛江分公司`
   - 子部门名称：`护士`

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

3. **创建/更新子部门**：
   - 父节点：对应的分公司
   - 记录`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. 执行数据库脚本
```bash
# 添加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. 重启后端服务
```bash
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` - 添加菜单权限

## 注意事项

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

## 扩展说明

### 如果需要定时同步
可以在`ruoyi-quartz`模块中添加定时任务：

```java
@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