# 用户登录支持手机号功能说明

## 功能概述

系统登录接口已升级，现在支持两种登录方式：
1. **账号密码登录**：使用用户名 + 密码
2. **手机号密码登录**：使用手机号 + 密码

系统会自动识别用户输入的是手机号还是账号，无需额外指定登录类型。

## 实现原理

### 1. 判断逻辑

系统通过正则表达式自动识别输入类型：
- **手机号格式**：匹配 `^1[3-9]\d{9}$`（1开头，第二位3-9，共11位数字）
- **用户名格式**：不符合手机号格式的视为用户名

### 2. 查询策略

```java
// 判断是否为手机号
if (username.matches("^1[3-9]\\d{9}$")) {
    // 通过手机号查询用户
    user = userService.selectUserByPhonenumber(username);
} else {
    // 通过用户名查询用户
    user = userService.selectUserByUserName(username);
}
```

## 修改文件清单

### 1. Service 接口层
**文件**: `ruoyi-system/src/main/java/com/ruoyi/system/service/ISysUserService.java`

新增方法：
```java
/**
 * 通过手机号查询用户
 * 
 * @param phonenumber 手机号
 * @return 用户对象信息
 */
public SysUser selectUserByPhonenumber(String phonenumber);
```

### 2. Service 实现层
**文件**: `ruoyi-system/src/main/java/com/ruoyi/system/service/impl/SysUserServiceImpl.java`

实现方法：
```java
@Override
public SysUser selectUserByPhonenumber(String phonenumber) {
    return userMapper.checkPhoneUnique(phonenumber);
}
```

### 3. 用户认证服务
**文件**: `ruoyi-framework/src/main/java/com/ruoyi/framework/web/service/UserDetailsServiceImpl.java`

修改 `loadUserByUsername` 方法：
- 增加手机号识别逻辑
- 根据输入类型调用不同的查询方法
- 增加详细的日志记录

### 4. 登录校验服务
**文件**: `ruoyi-framework/src/main/java/com/ruoyi/framework/web/service/SysLoginService.java`

修改 `loginPreCheck` 方法：
- 优化用户名长度校验（手机号登录时不校验用户名长度）
- 更新注释说明支持手机号登录

## 使用示例

### 场景1：使用账号登录

**请求**：
```json
POST /login
{
  "username": "admin",
  "password": "admin123",
  "code": "1234",
  "uuid": "xxx-xxx-xxx"
}
```

**处理流程**：
1. 系统识别 "admin" 不是手机号格式
2. 调用 `selectUserByUserName("admin")` 查询用户
3. 验证密码，生成 Token

### 场景2：使用手机号登录

**请求**：
```json
POST /login
{
  "username": "13800138000",
  "password": "password123",
  "code": "1234",
  "uuid": "xxx-xxx-xxx"
}
```

**处理流程**：
1. 系统识别 "13800138000" 是手机号格式
2. 调用 `selectUserByPhonenumber("13800138000")` 查询用户
3. 验证密码，生成 Token

## 日志记录

系统会记录详细的登录日志，便于追踪和排查问题：

```
尝试使用用户名登录：admin
尝试使用手机号登录：13800138000
```

## 注意事项

### 1. 手机号唯一性
- 系统中每个手机号必须唯一
- 手机号已在用户管理中配置唯一性校验

### 2. 密码校验
- 无论使用哪种方式登录，密码校验规则相同
- 密码长度限制：5-20位

### 3. 用户状态检查
- 账号已删除、已停用的用户无法登录
- 手机号和账号登录的状态检查逻辑一致

### 4. 安全机制
- IP 黑名单机制继续生效
- 密码错误次数限制继续生效
- 验证码机制继续生效

## 兼容性说明

### 向后兼容
- ✅ 原有账号登录方式完全兼容
- ✅ 现有用户无需任何修改即可继续使用
- ✅ API 接口未发生变化

### 前端适配
前端无需修改，直接将用户输入的账号或手机号传给 `username` 字段即可：

```javascript
// 原有代码无需修改
login({
  username: this.loginForm.username,  // 可以是账号或手机号
  password: this.loginForm.password,
  code: this.loginForm.code,
  uuid: this.loginForm.uuid
})
```

## 测试建议

### 1. 功能测试
- [x] 使用账号登录成功
- [x] 使用手机号登录成功
- [x] 使用不存在的账号登录失败
- [x] 使用不存在的手机号登录失败
- [x] 使用错误密码登录失败

### 2. 边界测试
- [x] 手机号格式校验（非11位、非1开头等）
- [x] 账号长度校验
- [x] 密码长度校验

### 3. 安全测试
- [x] 密码重试次数限制
- [x] IP 黑名单机制
- [x] 验证码机制

## 总结

此次改造实现了用户登录方式的灵活化，用户可以根据自己的习惯选择使用账号或手机号登录，提升了用户体验。同时保持了系统的安全性和稳定性，对现有功能完全兼容。