198 行
6.6 KiB
Markdown
198 行
6.6 KiB
Markdown
# feat(user): 管理端手机号验证码登录(短信路径免 2FA)
|
|
|
|
> **仓库**: HL (后端 hl-user-service + hl-gateway)
|
|
> **关联 PR/Issue**: PR #2904, Closes #2889
|
|
> **日期**: 2026-05-22
|
|
> **影响范围**: 管理后台登录页加「短信验证码登录」入口
|
|
> **接收方**: mmg (前端)
|
|
> **前端**: **需要改动 — 登录页加 tab + 手机号/验证码输入 + 倒计时按钮**
|
|
|
|
---
|
|
|
|
## 🚨 关键变化
|
|
|
|
新增 2 个接口,管理员可以用「手机号 + 短信验证码」登录后台,**短信路径本身不再走企业微信 2FA**(账号密码登录路径完全不动,仍保留 2FA)。
|
|
|
|
依赖前置工单 #2886 的 `admin_user.mobile` 字段(已上线)。
|
|
|
|
---
|
|
|
|
## 一、API 影响
|
|
|
|
### 新增 `POST /admin/auth/sms/send-code` 发送验证码
|
|
|
|
请求体:
|
|
|
|
```json
|
|
{
|
|
"mobile": "13800138000"
|
|
}
|
|
```
|
|
|
|
| 字段 | 类型 | 必填 | 校验 |
|
|
|------|------|-----|------|
|
|
| mobile | String | ✅ | `^1[3-9]\d{9}$` 11 位 |
|
|
|
|
响应:
|
|
|
|
| 场景 | code | message |
|
|
|------|------|---------|
|
|
| 注册 mobile 真发 | 200 | 成功 |
|
|
| **未注册 mobile**(防枚举) | **200** | **成功**(静默不真发,但日上限消费) |
|
|
| 60s 内重发 | 200105 | 发送过于频繁,请 60 秒后重试 |
|
|
| 当日 >= 10 次 | 200106 | 今日发送次数已达上限 |
|
|
| mobile 格式错 / 漏 | 400 | 手机号不能为空 / 手机号格式不正确 |
|
|
|
|
⚠️ **防枚举关键**: 未注册 mobile **也返 200** 跟"已注册"路径**外部不可区分**(末尾 300-800ms 随机 jitter 抹平时延)。前端不能依据 send-code 响应判断 mobile 是否注册。
|
|
|
|
### 新增 `POST /admin/auth/sms/login` 验证码登录
|
|
|
|
请求体:
|
|
|
|
```json
|
|
{
|
|
"mobile": "13800138000",
|
|
"code": "123456"
|
|
}
|
|
```
|
|
|
|
| 字段 | 类型 | 必填 | 校验 |
|
|
|------|------|-----|------|
|
|
| mobile | String | ✅ | `^1[3-9]\d{9}$` |
|
|
| code | String | ✅ | `^\d{6}$` 6 位数字 |
|
|
|
|
响应:
|
|
|
|
| 场景 | code | 说明 |
|
|
|------|------|------|
|
|
| 登录成功 | 200 | 返回 data = AdminLoginResponse(含 token, refreshToken, adminId, username, role, roleName, avatar, roles, **`requireTwoFa: false`**) |
|
|
| 验证码错 | 200102 | 验证码错误(fail+1) |
|
|
| 验证码过期/未发送 | 200103 | 验证码已过期,请重新获取(**fail 不增**) |
|
|
| 失败 >= 5 锁定 | 200104 | 短信登录失败次数过多,请 15 分钟后重试 |
|
|
| 对码 + mobile 不绑 admin | 200102 | 验证码错误(**防枚举,假装码错不报"用户不存在"**) |
|
|
|
|
⚠️ **`requireTwoFa: false` 是工单核心放行点**: 短信验证码本身是「拥有手机」的二次因子,与企微 2FA 等价,不再叠加。**账号密码登录的 requireTwoFa=true 行为完全不变**。
|
|
|
|
---
|
|
|
|
## 🚨 前端需要做的事
|
|
|
|
### 1. 登录页加「短信验证码登录」tab
|
|
|
|
文件: `hl-ui/src/views/login/...` (登录页组件)
|
|
|
|
跟现有「账号密码」「企业微信扫码」并列,加一个新 tab:
|
|
|
|
```
|
|
[ 账号密码 ] [ 企业微信扫码 ] [ 短信验证码 ]
|
|
```
|
|
|
|
### 2. 「短信验证码」表单
|
|
|
|
- 输入框 1: 手机号(11 位格式预校验 `^1[3-9]\d{9}$`)
|
|
- 按钮: 「获取验证码」点击 → POST `/admin/auth/sms/send-code`
|
|
- 点击后 60s 倒计时(按钮文案 `60s 后重新获取`),复用现有小程序短信发送倒计时组件
|
|
- 响应 200 → 提示「验证码已发送」(**注册/未注册都提示已发送,不能透露 mobile 是否绑**)
|
|
- 响应 200105 → 提示「发送过于频繁,请稍后重试」
|
|
- 响应 200106 → 提示「今日发送次数已达上限」
|
|
- 输入框 2: 验证码(6 位数字)
|
|
- 按钮:「登录」点击 → POST `/admin/auth/sms/login`
|
|
- 响应 200 + data → 走现有登录成功流程(存 token / 跳转,**不再触发 2FA 弹窗**)
|
|
- 响应 200102 → 提示「验证码错误」
|
|
- 响应 200103 → 提示「验证码已过期,请重新获取」并清空验证码输入
|
|
- 响应 200104 → 提示「失败次数过多,请 15 分钟后重试」并锁登录按钮 15min
|
|
|
|
### 3. 入口指引(可选)
|
|
|
|
在「账号密码」tab 下方加小字提示:
|
|
|
|
```
|
|
忘记密码? 试试 [短信验证码登录]
|
|
```
|
|
|
|
### 4. 自查
|
|
|
|
```bash
|
|
grep -rE "admin.*sms|短信验证码登录" hl-ui/src
|
|
```
|
|
|
|
---
|
|
|
|
## 二、错误码总览(本工单新增 5 个)
|
|
|
|
| code | 含义 |
|
|
|------|------|
|
|
| 200102 | 验证码错误 / 对码但 mobile 不绑 admin |
|
|
| 200103 | 验证码已过期 / 未发送 |
|
|
| 200104 | 短信登录失败次数过多(15 分钟锁定) |
|
|
| 200105 | 发送过于频繁(60s 间隔) |
|
|
| 200106 | 今日发送次数已达上限(10/d) |
|
|
|
|
---
|
|
|
|
## 三、安全设计
|
|
|
|
### 4 重防枚举攻击
|
|
|
|
1. 间隔锁 60s + 日上限 10/d **先于** admin 查询消费(未注册 mobile 也扣额度,防刷量)
|
|
2. 未注册 mobile **静默返 200** 不真发不存 code
|
|
3. 末尾 **300-800ms 随机 jitter** 防时间侧信道(注册/未注册路径外部时延无差异)
|
|
4. login 阶段 mobile 不绑 admin **即使码对也返 INVALID** 跟真错码路径不可区分
|
|
|
|
### Redis namespace 隔离
|
|
|
|
跟小程序端 `sms:*` 完全隔离,本接口用:
|
|
|
|
- `admin:sms:code:{mobile}` TTL 300s
|
|
- `admin:sms:interval:{mobile}` TTL 60s
|
|
- `admin:sms:limit:{mobile}` TTL 到当日午夜
|
|
- `admin:sms:fail:{mobile}` TTL 900s (15min)
|
|
|
|
### 失败计数策略
|
|
|
|
- 用 Redis `admin:sms:fail:{mobile}` 独立计数(**不动 `admin_user.failed_login_count`**,后者密码场景专用)
|
|
- 验证码错累加 → 累计 5 次锁 15 分钟
|
|
- 验证码过期/未发送**不累加**(防攻击者用别人 mobile 试码锁住真用户)
|
|
|
|
---
|
|
|
|
## 四、DB 改动
|
|
|
|
`hl-user-service`:
|
|
|
|
- `V20260523_002__login_log_method_to_varchar.sql`: `login_log.login_method` 从 ENUM(4 值) 改 `VARCHAR(32)`,新增 `SMS` 值,后续登录方式扩展无需改 DDL
|
|
|
|
---
|
|
|
|
## 五、测试服验证记录
|
|
|
|
部署到测试服 (`https://web.test.1814.love:9443` 网关 + `hl-user-service` 双实例) 后已 round-trip 验证 (2026-05-22 16:55):
|
|
|
|
| # | 场景 | 预期 | 实测 |
|
|
|---|------|------|------|
|
|
| T1 | send-code 注册 mobile | 200 + Redis 存 code | ✅ code='505310' |
|
|
| T2 | 60s 重发 | 200105 | ✅ |
|
|
| T3 | send-code 未注册 mobile | 200 静默 Redis 无 code | ✅ 防枚举 |
|
|
| T4 | login 对码 | 200 + token + role + **requireTwoFa=False** | ✅ |
|
|
| T7 | 对码 + mobile 不绑 admin | 200102 INVALID | ✅ 防枚举 |
|
|
| T8 | 5 次错码累加锁定 | fail 1→5, 第 6 次 200104 | ✅ |
|
|
|
|
测试服 user 双实例 + gateway 双实例都已部署 dev 最新,可联调。
|
|
|
|
---
|
|
|
|
## 六、不在本期范围
|
|
|
|
- 「忘记密码走短信重置」(另起工单)
|
|
- 完全废弃企微 2FA (账密登录链路保留 2FA)
|
|
- 注册 mobile 检查接口(防枚举设计不暴露)
|
|
|
|
---
|
|
|
|
## 七、联系人
|
|
|
|
后端: wx(呼籁旅行)
|
|
前端: mmg
|
|
|
|
如有疑问可在 [#2889](https://git.1814.love:8443/wx/HL/issues/2889) 评论区留言。
|