# 用户同步功能 - 快速开始

## 一、功能说明
从SQL Server的OA_User表同步用户数据到若依系统，通过`department_id`自动关联部门。

## 二、前置条件
⚠️ **必须先完成部门同步！** 用户同步依赖部门数据。

## 三、安装步骤

### 1️⃣ 执行数据库脚本
```bash
# 1. 部门表添加字段（如果未执行）
mysql -u root -p ry-vue < sql/add_department_id_to_sys_dept.sql

# 2. 用户表添加字段
mysql -u root -p ry-vue < sql/add_oa_user_id_to_sys_user.sql
```

### 2️⃣ 编译项目
```bash
mvn clean package -DskipTests
```

### 3️⃣ 启动服务
```bash
cd ruoyi-admin
java -jar target/ruoyi-admin.jar
```

## 四、使用方法

### ⚠️ 重要：必须按顺序执行

#### 第一步：同步部门
```bash
POST http://localhost:8080/system/dept/sync/branch
Headers:
  Authorization: Bearer {你的token}
```

#### 第二步：同步用户
```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
  }
}
```

## 六、验证结果
```sql
-- 查看同步的用户
SELECT 
    u.user_name,
    u.nick_name,
    u.oa_user_id,
    d.dept_name,
    u.email,
    u.phonenumber
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;
```

## 七、核心逻辑

### 部门关联
```
OA_departmentID → 查询sys_dept.department_id → 获取dept_id
```

### 用户处理
```
1. 根据oa_user_id查询
   ├─ 存在 → 更新用户信息
   └─ 不存在
      ├─ 用户名存在 → 更新并设置oa_user_id
      └─ 用户名不存在 → 创建新用户（密码123456）
```

## 八、默认值说明
新创建用户的默认设置：
- 🔑 **密码**: `123456`
- 🏢 **部门**: 100（若依科技）- 如果找不到对应部门
- 👤 **性别**: 2（未知）
- ✅ **状态**: 0（正常）

## 九、核心文件清单

### SQL脚本
- `sql/add_oa_user_id_to_sys_user.sql` - 添加字段

### Java文件
- `SysUser.java`（修改） - 添加oaUserId字段
- `UserSyncDTO.java` - 用户数据传输对象
- `UserSyncMapper.java` + XML - 查询SQL Server
- `SysUserMapper.java/XML`（扩展） - 扩展查询方法
- `IUserSyncService.java` - 服务接口
- `UserSyncServiceImpl.java` - 核心同步逻辑
- `DepartmentSyncController.java`（扩展） - 添加接口

### 文档
- `prd/用户同步功能说明.md` - 详细说明

## 十、常见问题

### ❌ 用户部门为空？
**原因**: 部门未同步或department_id不匹配
**解决**: 先执行部门同步

### ❌ 用户名重复？
**处理**: 自动更新已存在用户的oa_user_id，不会报错

### ❓ 新用户如何登录？
**账号**: OA_User字段值
**密码**: `123456`
**建议**: 首次登录后修改密码

## 十一、注意事项

✅ **执行顺序很重要**
1. 先同步部门
2. 再同步用户

✅ **幂等性保证**
- 多次同步不会创建重复数据
- 已存在用户只会更新信息

✅ **权限要求**
- 部门同步: `system:dept:sync`
- 用户同步: `system:user:sync`

## 十二、监控与日志

### 查看日志
```bash
tail -f ruoyi-admin/logs/sys-info.log | grep -i "UserSync"
```

### 日志示例
```
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, 跳过: 3, 失败: 2
```

## 十三、下一步

### 前端集成
在用户管理页面添加"同步"按钮：
```javascript
syncUsers() {
  this.$confirm('确认同步OA用户数据吗？', '提示', {
    type: 'warning'
  }).then(() => {
    this.$http.post('/system/dept/sync/user').then(res => {
      this.$message.success(res.msg);
      this.getList();
    });
  });
}
```

### 定时任务
配置每天自动同步：
- 任务名称: OA用户同步
- 调用目标: `userSyncTask.execute`
- cron表达式: `0 0 3 * * ?` (每天凌晨3点)

## 十四、相关文档
- [用户同步详细说明](prd/用户同步功能说明.md)
- [部门同步快速开始](部门同步-快速开始.md)