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

## 🎯 系统概述

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

### 核心功能
1. **部门同步**: 同步组织架构（分公司和部门）
2. **用户同步**: 同步用户数据并自动关联部门

### 技术架构
- **数据源**: 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 执行数据库脚本
```bash
# 进入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`

```yaml
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 编译启动
```bash
# 编译项目
mvn clean package -DskipTests

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

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

#### 2.1 先同步部门
```bash
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 再同步用户
```bash
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 验证部门同步
```sql
-- 查看同步的分公司
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 验证用户同步
```sql
-- 查看同步的用户
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）
```

## 💡 核心逻辑

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

### 用户同步逻辑
1. 查询SQL Server的OA_User表
2. 根据OA_departmentID关联sys_dept获取dept_id
3. 根据oa_user_id查询用户是否存在
4. 存在则更新，不存在则创建
5. 新用户默认密码为123456

## ⚙️ 配置说明

### 数据库字段扩展

#### sys_dept表
```sql
department_id INT NULL  -- SQL Server中的departmentID
```

#### sys_user表
```sql
oa_user_id INT NULL  -- SQL Server中的OA_User_ID
```

### 默认值设置

#### 新用户默认值
- **密码**: `123456`（加密存储）
- **部门**: 100（若依科技）- 找不到部门时
- **性别**: 2（未知）
- **状态**: 0（正常）

#### 分公司默认值
- **父部门**: 100（若依科技）
- **状态**: 0（正常）
- **创建者**: sync

## 🔧 特性说明

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

### ✅ 事务保护
- 使用`@Transactional`注解
- 同步失败自动回滚
- 保证数据一致性

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

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

## 📊 监控与日志

### 查看日志
```bash
# 查看部门同步日志
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. 增量同步: 每小时一次（可选）
```

### 安全建议
1. 新用户首次登录强制修改密码
2. 定期检查同步日志
3. 监控同步失败情况
4. 备份数据库

## 📁 文件清单

### 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` - 本文档

## 🔗 相关资源

### 详细文档
- [部门同步详细说明](prd/部门同步功能说明.md)
- [用户同步详细说明](prd/用户同步功能说明.md)

### 快速指南
- [部门同步快速开始](部门同步-快速开始.md)
- [用户同步快速开始](用户同步-快速开始.md)

### 开发总结
- [部门同步开发总结](部门同步功能开发总结.md)
- [用户同步开发总结](用户同步功能开发总结.md)

## 👨‍💻 技术支持

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

## ✅ 总结

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

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

---

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