# 用户手机号唯一性 - 快速参考

## 🎯 核心目标

**确保手机号在系统中的全局唯一性，避免登录冲突**

## 📋 覆盖功能

| 功能 | 校验状态 | 说明 |
|------|---------|------|
| ✅ 用户添加 | 已有 | Controller层校验 |
| ✅ 用户修改 | 已有 | Controller层校验 |
| ✅ 用户导入 | **新增** | Service层校验 |
| ✅ 用户同步(新增) | **新增** | Service层校验 |
| ✅ 用户同步(更新) | **新增** | Service层校验 |

## 🔧 修改文件

### 1. SysUserServiceImpl.java
**方法**: `importUser`

```java
// 新增用户：校验手机号唯一性
if (StringUtils.isNotEmpty(user.getPhonenumber())) {
    SysUser phoneCheck = userMapper.checkPhoneUnique(user.getPhonenumber());
    if (StringUtils.isNotNull(phoneCheck)) {
        // 拒绝导入，记录错误
    }
}

// 更新用户：校验手机号唯一性（排除自己）
if (StringUtils.isNotEmpty(user.getPhonenumber())) {
    SysUser phoneCheck = userMapper.checkPhoneUnique(user.getPhonenumber());
    if (StringUtils.isNotNull(phoneCheck) && !phoneCheck.getUserId().equals(u.getUserId())) {
        // 拒绝更新，记录错误
    }
}
```

### 2. UserSyncServiceImpl.java

#### createNewUser
```java
// 创建前检查
SysUser phoneCheck = sysUserMapper.checkPhoneUnique(dto.getPhonenumber());
if (StringUtils.isNotNull(phoneCheck)) {
    log.warn("手机号重复，跳过创建");
    return; // 跳过
}
```

#### updateExistingUser
```java
// 更新前检查（排除自己）
SysUser phoneCheck = sysUserMapper.checkPhoneUnique(dto.getPhonenumber());
if (StringUtils.isNotNull(phoneCheck) && !phoneCheck.getUserId().equals(existingUser.getUserId())) {
    log.warn("手机号被占用，跳过手机号更新");
    // 继续更新其他字段
}
```

## 🎨 处理策略

### 用户导入
- **策略**: 严格拒绝
- **行为**: 终止导入该记录，显示错误信息

### 用户同步
- **策略**: 容错处理  
- **行为**: 跳过冲突字段，继续其他字段，记录警告

## 📝 错误提示

### 导入
```
账号 zhangsan 导入失败：手机号码 13800138000 已被用户 lisi 使用
```

### 同步
```log
创建用户失败，手机号 13800138000 已被用户 lisi 使用，跳过用户 zhangsan
```

## ✅ 测试清单

- [ ] 导入新用户，手机号重复 → 拒绝
- [ ] 导入新用户，手机号唯一 → 成功
- [ ] 更新用户，手机号改为已占用 → 拒绝
- [ ] 更新用户，手机号不变 → 成功
- [ ] 同步新用户，手机号重复 → 跳过创建
- [ ] 同步更新，手机号被占用 → 跳过该字段

## 💡 数据库约束（可选）

```sql
CREATE UNIQUE INDEX idx_sys_user_phonenumber 
ON sys_user(phonenumber) 
WHERE phonenumber IS NOT NULL 
  AND phonenumber != '' 
  AND del_flag = '0';
```

## 🔗 相关文档

- [详细说明](./用户手机号唯一性完善说明.md)
- [登录支持手机号](./用户登录支持手机号功能说明.md)