853 lines
27 KiB
Markdown
853 lines
27 KiB
Markdown
# 多方式登录与第三方登录设计文档
|
||
|
||
> **日期**: 2026-06-07
|
||
> **状态**: 已批准，待实现
|
||
> **作者**: AI Assistant
|
||
|
||
---
|
||
|
||
## 1. 背景与目标
|
||
|
||
### 1.1 现状
|
||
|
||
当前系统仅支持用户名密码登录（`grant_type=password`），且 `PasswordAuthenticationConverter` 只提取 `username` 参数，无法支持手机号、邮箱登录。微信、支付宝、短信登录的 `Converter` 和 `Provider` 均为空实现。
|
||
|
||
### 1.2 目标
|
||
|
||
1. **扩展密码登录**：支持用户名、手机号、邮箱三种账号类型登录
|
||
2. **实现短信登录**：框架结构先行，验证码逻辑后续填充
|
||
3. **实现微信登录**：支持微信授权码换取用户信息并自动创建账号
|
||
4. **实现支付宝登录**：支持支付宝授权码换取用户信息并自动创建账号
|
||
5. **第三方账号管理**：存储 openId/unionId，支持 unionId 优先查询
|
||
6. **手机号为主键**：系统以手机号作为用户唯一标识，第三方登录自动创建新用户
|
||
7. **字段迁移**：将 `email` 从 `uc_user_detail` 迁移到 `uc_user` 表
|
||
|
||
---
|
||
|
||
## 2. 核心设计原则
|
||
|
||
1. **独立授权模式**：每种登录方式使用独立的 `grant_type`，符合 OAuth2 扩展规范
|
||
2. **手机号唯一性**：手机号是系统用户的唯一标识，第三方登录时优先用手机号创建/查找用户
|
||
3. **自动创建用户**：第三方登录无手机号时，自动生成 `userNo` 作为用户名，后续用户可自行修改
|
||
4. **unionId 优先**：查询第三方用户信息时，优先使用 unionId，其次使用 openId
|
||
5. **向后兼容**：保留现有 `password` 模式的 `username` 参数，同时新增 `account` + `accountType` 参数
|
||
|
||
---
|
||
|
||
## 3. 架构设计
|
||
|
||
### 3.1 整体架构
|
||
|
||
```
|
||
前端调用
|
||
│
|
||
▼
|
||
POST /oauth2/token
|
||
│
|
||
▼
|
||
┌─────────────────────────────────────┐
|
||
│ DelegatingAuthenticationConverter │
|
||
│ ┌─────────┐ ┌─────┐ ┌─────────┐ │
|
||
│ │ Password│ │ Sms │ │ Wechat │ │
|
||
│ │ Converter│ │Converter│ │Converter│ │
|
||
│ └─────────┘ └─────┘ └─────────┘ │
|
||
│ ┌─────────┐ │
|
||
│ │ Alipay │ │
|
||
│ │Converter│ │
|
||
│ └─────────┘ │
|
||
└─────────────────────────────────────┘
|
||
│
|
||
▼
|
||
┌─────────────────────────────────────┐
|
||
│ AuthenticationProvider 链 │
|
||
│ ┌─────────┐ ┌─────┐ ┌─────────┐ │
|
||
│ │ Password│ │ Sms │ │ Wechat │ │
|
||
│ │ Provider│ │Provider│ │Provider│ │
|
||
│ └─────────┘ └─────┘ └─────────┘ │
|
||
│ ┌─────────┐ │
|
||
│ │ Alipay │ │
|
||
│ │Provider │ │
|
||
│ └─────────┘ │
|
||
└─────────────────────────────────────┘
|
||
│
|
||
▼
|
||
┌─────────────────────────────────────┐
|
||
│ 用户查找 / 创建 / 绑定 │
|
||
│ • 根据手机号/用户名/邮箱查找用户 │
|
||
│ • 第三方登录：调平台API获取用户信息 │
|
||
│ • 自动创建新用户（手机号或userNo） │
|
||
│ • 记录第三方绑定关系 │
|
||
└─────────────────────────────────────┘
|
||
│
|
||
▼
|
||
┌─────────────────────────────────────┐
|
||
│ 生成 OAuth2 Token │
|
||
│ Access Token + Refresh Token │
|
||
└─────────────────────────────────────┘
|
||
```
|
||
|
||
### 3.2 登录方式对照表
|
||
|
||
| 登录方式 | grant_type | 必填参数 | 可选参数 | 说明 |
|
||
|---------|-----------|---------|---------|------|
|
||
| 用户名密码 | `password` | `username`, `password` | - | 兼容现有方式 |
|
||
| 手机号密码 | `password` | `account`, `accountType=PHONE`, `password` | - | 扩展方式 |
|
||
| 邮箱密码 | `password` | `account`, `accountType=EMAIL`, `password` | - | 扩展方式 |
|
||
| 短信验证码 | `sms` | `phone`, `code` | - | 框架先行 |
|
||
| 微信登录 | `wechat` | `code` | `phone` | 授权码模式 |
|
||
| 支付宝登录 | `alipay` | `code` | `phone` | 授权码模式 |
|
||
|
||
---
|
||
|
||
## 4. 数据库设计
|
||
|
||
### 4.1 新增表：`rui_uc_user_social`
|
||
|
||
存储用户与第三方平台的绑定关系。
|
||
|
||
```sql
|
||
CREATE TABLE rui_uc_user_social (
|
||
id BIGINT NOT NULL,
|
||
tenant_id BIGINT NOT NULL DEFAULT 0 COMMENT '租户ID',
|
||
user_id BIGINT NOT NULL COMMENT '用户ID',
|
||
provider VARCHAR(20) NOT NULL COMMENT '平台 wechat/alipay',
|
||
union_id VARCHAR(100) DEFAULT NULL COMMENT 'unionId（微信开放平台）',
|
||
open_id VARCHAR(100) NOT NULL COMMENT 'openId',
|
||
extra JSON DEFAULT NULL COMMENT '扩展信息（昵称、头像等）',
|
||
created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3),
|
||
updated_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3),
|
||
PRIMARY KEY (id),
|
||
UNIQUE KEY uk_user_provider (user_id, provider),
|
||
UNIQUE KEY uk_provider_openid (provider, open_id),
|
||
INDEX idx_union_id (union_id),
|
||
INDEX idx_user_id (user_id)
|
||
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='用户第三方账号关联';
|
||
```
|
||
|
||
**字段说明**：
|
||
- `provider`: 平台标识，`wechat` 或 `alipay`
|
||
- `union_id`: 微信开放平台统一标识，同一主体下的不同应用 unionId 相同
|
||
- `open_id`: 各应用内的唯一标识
|
||
- `extra`: JSON 格式，存储第三方平台的额外信息（昵称、头像、性别等）
|
||
|
||
**索引设计**：
|
||
- `uk_user_provider`: 一个用户在同一平台只能绑定一个账号
|
||
- `uk_provider_openid`: 同一平台的 openId 唯一
|
||
- `idx_union_id`: 支持 unionId 查询
|
||
|
||
### 4.2 修改表：`rui_uc_user`
|
||
|
||
新增 `email` 字段：
|
||
|
||
```sql
|
||
-- 在 rui_uc_user 表中添加 email 字段
|
||
ALTER TABLE rui_uc_user ADD COLUMN email VARCHAR(100) DEFAULT NULL COMMENT '邮箱' AFTER phone;
|
||
ALTER TABLE rui_uc_user ADD UNIQUE KEY uk_email (tenant_id, email);
|
||
```
|
||
|
||
修改后的表结构：
|
||
|
||
```sql
|
||
CREATE TABLE rui_uc_user (
|
||
id BIGINT NOT NULL,
|
||
tenant_id BIGINT NOT NULL DEFAULT 0 COMMENT '租户ID 0:系统级',
|
||
username VARCHAR(100) NOT NULL COMMENT '用户名',
|
||
phone VARCHAR(20) DEFAULT NULL COMMENT '手机号',
|
||
email VARCHAR(100) DEFAULT NULL COMMENT '邮箱',
|
||
user_no VARCHAR(50) DEFAULT NULL COMMENT '用户编号（短编码，前端展示用）',
|
||
password VARCHAR(255) NOT NULL COMMENT '密码（BCrypt加密）',
|
||
user_type TINYINT NOT NULL DEFAULT 1 COMMENT '用户类型 1:普通用户 2:管理员 3:系统用户',
|
||
status TINYINT NOT NULL DEFAULT 1 COMMENT '状态 0:禁用 1:启用',
|
||
deleted TINYINT NOT NULL DEFAULT 0 COMMENT '逻辑删除 0:正常 1:已删',
|
||
created_by BIGINT DEFAULT NULL COMMENT '创建者ID',
|
||
created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3),
|
||
updated_by BIGINT DEFAULT NULL COMMENT '更新者ID',
|
||
updated_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3),
|
||
PRIMARY KEY (id),
|
||
UNIQUE KEY uk_username (tenant_id, username),
|
||
UNIQUE KEY uk_phone (tenant_id, phone),
|
||
UNIQUE KEY uk_email (tenant_id, email),
|
||
INDEX idx_tenant (tenant_id),
|
||
INDEX idx_status (status)
|
||
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='用户';
|
||
```
|
||
|
||
### 4.3 修改表：`rui_uc_user_detail`
|
||
|
||
删除 `email` 字段：
|
||
|
||
```sql
|
||
-- 从 rui_uc_user_detail 表中删除 email 字段
|
||
ALTER TABLE rui_uc_user_detail DROP COLUMN email;
|
||
```
|
||
|
||
### 4.4 登录日志扩展
|
||
|
||
`rui_sys_login_log` 表的 `login_type` 字段已有定义：
|
||
- `1`: 密码登录
|
||
- `2`: 短信登录
|
||
- `3`: 微信登录
|
||
- `4`: 支付宝登录
|
||
|
||
**无需修改**，但需要在代码中确保所有登录方式都正确记录类型。
|
||
|
||
---
|
||
|
||
## 5. 核心流程设计
|
||
|
||
### 5.1 密码登录流程（扩展）
|
||
|
||
```
|
||
前端请求
|
||
│
|
||
▼
|
||
POST /oauth2/token
|
||
Content-Type: application/x-www-form-urlencoded
|
||
Authorization: Basic {client_credentials}
|
||
|
||
# 方式1：用户名密码（兼容现有）
|
||
grant_type=password
|
||
&username=admin
|
||
&password=123456
|
||
|
||
# 方式2：手机号密码（新增）
|
||
grant_type=password
|
||
&account=13800138000
|
||
&accountType=PHONE
|
||
&password=123456
|
||
|
||
# 方式3：邮箱密码（新增）
|
||
grant_type=password
|
||
&account=user@example.com
|
||
&accountType=EMAIL
|
||
&password=123456
|
||
│
|
||
▼
|
||
PasswordAuthenticationConverter
|
||
├─ 提取 grant_type=password
|
||
├─ 如果有 username → 走兼容模式
|
||
└─ 如果有 account + accountType → 走扩展模式
|
||
│
|
||
▼
|
||
PasswordAuthenticationProvider
|
||
├─ 校验客户端支持 password 授权
|
||
├─ 构建 UsernamePasswordAuthenticationToken
|
||
│ ├─ 兼容模式: username 作为 principal
|
||
│ └─ 扩展模式: account 作为 principal
|
||
│
|
||
▼
|
||
AuthenticationManager
|
||
│
|
||
▼
|
||
DaoAuthenticationProvider
|
||
├─ 调用 RemoteUserDetailsService.loadUserByUsername(username)
|
||
│ 或 RemoteUserDetailsService.loadUserByAccount(account, accountType)
|
||
│
|
||
▼
|
||
RemoteUserDetailsService
|
||
├─ USERNAME → userAuthFeign.loadUser(account)
|
||
├─ PHONE → userAuthFeign.loadUser({account, PHONE})
|
||
└─ EMAIL → userAuthFeign.loadUser({account, EMAIL})
|
||
│
|
||
▼
|
||
UserInnerController.loadUser(LoginAccountDTO)
|
||
├─ 根据 accountType 查询用户
|
||
├─ PHONE → lambdaQuery().eq(User::getPhone, account)
|
||
├─ EMAIL → lambdaQuery().eq(User::getEmail, account)
|
||
└─ USERNAME → lambdaQuery().eq(User::getUsername, account)
|
||
│
|
||
▼
|
||
返回 UserDetails → 生成 Token
|
||
```
|
||
|
||
### 5.2 短信登录流程
|
||
|
||
```
|
||
前端请求
|
||
│
|
||
▼
|
||
POST /oauth2/token
|
||
grant_type=sms
|
||
&phone=13800138000
|
||
&code=123456
|
||
│
|
||
▼
|
||
SmsAuthenticationConverter
|
||
├─ 校验 grant_type=sms
|
||
├─ 校验 phone 必填
|
||
└─ 校验 code 必填
|
||
│
|
||
▼
|
||
SmsAuthenticationProvider
|
||
├─ 校验客户端支持 sms 授权
|
||
├─ 从 Redis 获取验证码（key: sms:code:{phone}）
|
||
├─ 比对验证码
|
||
├─ 验证码错误 → 抛出异常
|
||
└─ 验证码正确 → 继续
|
||
│
|
||
▼
|
||
根据 phone 查询用户
|
||
├─ 找到 → 生成 Token
|
||
└─ 未找到 → 创建新用户
|
||
├─ username = phone
|
||
├─ phone = phone
|
||
├─ password = 随机生成（BCrypt加密）
|
||
└─ user_no = 自动生成
|
||
│
|
||
▼
|
||
生成 OAuth2 Token
|
||
```
|
||
|
||
**注意**：短信验证码发送接口（`POST /sms/send`）本次不实现，只预留框架结构。Redis 中的验证码需要前端开发时手动设置或通过其他方式注入。
|
||
|
||
### 5.3 微信登录流程
|
||
|
||
```
|
||
前端请求
|
||
│
|
||
▼
|
||
POST /oauth2/token
|
||
grant_type=wechat
|
||
&code=wx_auth_code
|
||
&phone=13800138000 ← 可选
|
||
│
|
||
▼
|
||
WechatAuthenticationConverter
|
||
├─ 校验 grant_type=wechat
|
||
├─ 校验 code 必填
|
||
└─ 提取 phone（可选）
|
||
│
|
||
▼
|
||
WechatAuthenticationProvider
|
||
├─ 校验客户端支持 wechat 授权
|
||
├─ 调用微信 API 换取 access_token
|
||
│ GET https://api.weixin.qq.com/sns/oauth2/access_token
|
||
│ ?appid={appid}&secret={secret}&code={code}&grant_type=authorization_code
|
||
│
|
||
├─ 获取 openId, unionId, access_token
|
||
│
|
||
├─ 根据 unionId 查询 rui_uc_user_social
|
||
│ ├─ 找到 → 获取 user_id → 查询用户 → 生成 Token
|
||
│ └─ 未找到 → 根据 openId 查询
|
||
│ ├─ 找到 → 获取 user_id → 查询用户 → 生成 Token
|
||
│ └─ 未找到 → 创建新用户
|
||
│
|
||
▼
|
||
创建新用户流程
|
||
├─ 有 phone 参数
|
||
│ ├─ 查询 phone 是否已存在
|
||
│ ├─ 存在 → 使用该用户，记录绑定关系
|
||
│ └─ 不存在 → 创建新用户
|
||
│ ├─ username = phone
|
||
│ ├─ phone = phone
|
||
│ └─ password = 随机生成
|
||
│
|
||
└─ 无 phone 参数
|
||
├─ username = 随机生成（如 WX_ + 时间戳）
|
||
├─ phone = null
|
||
└─ password = 随机生成
|
||
│
|
||
▼
|
||
记录绑定关系
|
||
INSERT INTO rui_uc_user_social
|
||
(user_id, provider, union_id, open_id, extra)
|
||
VALUES (?, 'wechat', ?, ?, ?)
|
||
│
|
||
▼
|
||
生成 OAuth2 Token
|
||
```
|
||
|
||
### 5.4 支付宝登录流程
|
||
|
||
与微信登录类似，区别：
|
||
1. 调用支付宝 API：`alipay.system.oauth.token` 换取 access_token
|
||
2. 调用 `alipay.user.info.share` 获取用户信息
|
||
3. 支付宝没有 unionId，使用 userId 作为唯一标识
|
||
4. 存储到 `rui_uc_user_social` 时，`union_id` 为 null
|
||
|
||
---
|
||
|
||
## 6. 代码结构
|
||
|
||
### 6.1 新增/修改文件清单
|
||
|
||
#### rui-common-oauth2 模块
|
||
|
||
```
|
||
rui-common-oauth2/src/main/java/com/rui/common/oauth2/
|
||
├── authentication/
|
||
│ ├── BaseAuthenticationConverter.java # 已有，无需修改
|
||
│ ├── BaseAuthenticationProvider.java # 已有，无需修改
|
||
│ ├── password/
|
||
│ │ ├── PasswordAuthenticationConverter.java # 修改：支持 accountType
|
||
│ │ └── PasswordAuthenticationProvider.java # 已有，无需修改
|
||
│ ├── sms/
|
||
│ │ ├── SmsAuthenticationConverter.java # 重写：实现短信参数提取
|
||
│ │ ├── SmsAuthenticationProvider.java # 重写：实现短信认证逻辑
|
||
│ │ └── SmsAuthenticationToken.java # 新增：短信认证令牌
|
||
│ ├── weixin/
|
||
│ │ ├── WeixinAuthenticationConverter.java # 重写：实现微信参数提取
|
||
│ │ ├── WeixinAuthenticationProvider.java # 重写：实现微信认证逻辑
|
||
│ │ └── WeixinAuthenticationToken.java # 新增：微信认证令牌
|
||
│ └── alipay/
|
||
│ ├── AlipayAuthenticationConverter.java # 重写：实现支付宝参数提取
|
||
│ ├── AlipayAuthenticationProvider.java # 重写：实现支付宝认证逻辑
|
||
│ └── AlipayAuthenticationToken.java # 新增：支付宝认证令牌
|
||
├── config/
|
||
│ └── OAuth2ServerConfig.java # 修改：注册新的 Converter 和 Provider
|
||
└── service/
|
||
└── RemoteUserDetailsService.java # 修改：支持 EMAIL 类型
|
||
```
|
||
|
||
#### rui-service-user 模块
|
||
|
||
```
|
||
rui-service-user/src/main/java/com/rui/service/user/
|
||
├── entity/
|
||
│ ├── User.java # 修改：新增 email 字段
|
||
│ ├── UserDetail.java # 修改：删除 email 字段
|
||
│ └── UserSocial.java # 新增：第三方账号关联实体
|
||
├── mapper/
|
||
│ └── UserSocialMapper.java # 新增
|
||
├── service/
|
||
│ ├── IUserSocialService.java # 新增
|
||
│ └── impl/
|
||
│ └── UserSocialServiceImpl.java # 新增
|
||
├── controller/
|
||
│ └── inner/
|
||
│ └── UserInnerController.java # 修改：支持 EMAIL 查询
|
||
└── dto/
|
||
└── LoginAccountDTO.java # 已有，无需修改
|
||
```
|
||
|
||
### 6.2 关键类设计
|
||
|
||
#### 6.2.1 PasswordAuthenticationConverter（修改）
|
||
|
||
```java
|
||
public class PasswordAuthenticationConverter extends BaseAuthenticationConverter<PasswordAuthenticationToken> {
|
||
|
||
@Override
|
||
public void checkParams(HttpServletRequest request) {
|
||
MultiValueMap<String, String> parameters = OAuth2EndpointUtils.getParameters(request);
|
||
|
||
// 兼容模式：使用 username
|
||
String username = parameters.getFirst("username");
|
||
if (StringUtils.hasText(username)) {
|
||
// 校验 password
|
||
String password = parameters.getFirst("password");
|
||
if (!StringUtils.hasText(password)) {
|
||
OAuth2EndpointUtils.throwError(OAuth2ErrorCodes.INVALID_REQUEST, "password", ...);
|
||
}
|
||
return;
|
||
}
|
||
|
||
// 扩展模式：使用 account + accountType
|
||
String account = parameters.getFirst("account");
|
||
if (!StringUtils.hasText(account)) {
|
||
OAuth2EndpointUtils.throwError(OAuth2ErrorCodes.INVALID_REQUEST, "account", ...);
|
||
}
|
||
|
||
String accountType = parameters.getFirst("accountType");
|
||
if (!StringUtils.hasText(accountType)) {
|
||
OAuth2EndpointUtils.throwError(OAuth2ErrorCodes.INVALID_REQUEST, "accountType", ...);
|
||
}
|
||
|
||
// 校验 password
|
||
String password = parameters.getFirst("password");
|
||
if (!StringUtils.hasText(password)) {
|
||
OAuth2EndpointUtils.throwError(OAuth2ErrorCodes.INVALID_REQUEST, "password", ...);
|
||
}
|
||
}
|
||
|
||
@Override
|
||
public PasswordAuthenticationToken buildToken(...) {
|
||
// 将 accountType 放入 additionalParameters
|
||
// 供 Provider 使用
|
||
return new PasswordAuthenticationToken(...);
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 6.2.2 WechatAuthenticationProvider（重写）
|
||
|
||
```java
|
||
@Slf4j
|
||
public class WechatAuthenticationProvider extends BaseAuthenticationProvider<WechatAuthenticationToken> {
|
||
|
||
private final WechatApiClient wechatApiClient;
|
||
private final UserSocialService userSocialService;
|
||
private final UserService userService;
|
||
|
||
@Override
|
||
public UsernamePasswordAuthenticationToken buildToken(Map<String, Object> reqParameters) {
|
||
String code = (String) reqParameters.get("code");
|
||
String phone = (String) reqParameters.get("phone");
|
||
|
||
// 调用微信 API 获取 openId, unionId
|
||
WechatTokenResponse wxResponse = wechatApiClient.getAccessToken(code);
|
||
String openId = wxResponse.getOpenid();
|
||
String unionId = wxResponse.getUnionid();
|
||
|
||
// 查找或创建用户
|
||
User user = findOrCreateUser(openId, unionId, phone);
|
||
|
||
// 构建认证令牌
|
||
return new UsernamePasswordAuthenticationToken(user.getUsername(), null);
|
||
}
|
||
|
||
private User findOrCreateUser(String openId, String unionId, String phone) {
|
||
// 1. 根据 unionId 查找
|
||
if (StringUtils.hasText(unionId)) {
|
||
UserSocial social = userSocialService.findByUnionId(unionId);
|
||
if (social != null) {
|
||
return userService.getById(social.getUserId());
|
||
}
|
||
}
|
||
|
||
// 2. 根据 openId 查找
|
||
UserSocial social = userSocialService.findByOpenId("wechat", openId);
|
||
if (social != null) {
|
||
return userService.getById(social.getUserId());
|
||
}
|
||
|
||
// 3. 创建新用户
|
||
User user = new User();
|
||
if (StringUtils.hasText(phone)) {
|
||
// 检查手机号是否已存在
|
||
User existUser = userService.findByPhone(phone);
|
||
if (existUser != null) {
|
||
user = existUser;
|
||
} else {
|
||
user.setUsername(phone);
|
||
user.setPhone(phone);
|
||
user.setPassword(generateRandomPassword());
|
||
userService.save(user);
|
||
}
|
||
} else {
|
||
// 无手机号，生成随机用户名
|
||
user.setUsername(generateRandomUsername());
|
||
user.setPassword(generateRandomPassword());
|
||
userService.save(user);
|
||
}
|
||
|
||
// 4. 记录绑定关系
|
||
UserSocial newSocial = new UserSocial();
|
||
newSocial.setUserId(user.getId());
|
||
newSocial.setProvider("wechat");
|
||
newSocial.setUnionId(unionId);
|
||
newSocial.setOpenId(openId);
|
||
userSocialService.save(newSocial);
|
||
|
||
return user;
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 6.2.3 UserSocial 实体
|
||
|
||
```java
|
||
@Data
|
||
@TableName(value = "uc_user_social", keepGlobalPrefix = true)
|
||
public class UserSocial extends BaseEntity {
|
||
|
||
@Schema(description = "用户ID")
|
||
private Long userId;
|
||
|
||
@Schema(description = "平台 wechat/alipay")
|
||
private String provider;
|
||
|
||
@Schema(description = "unionId")
|
||
private String unionId;
|
||
|
||
@Schema(description = "openId")
|
||
private String openId;
|
||
|
||
@Schema(description = "扩展信息")
|
||
private String extra;
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 7. API 接口设计
|
||
|
||
### 7.1 密码登录
|
||
|
||
```http
|
||
### 用户名密码登录（兼容现有）
|
||
POST /oauth2/token
|
||
Content-Type: application/x-www-form-urlencoded
|
||
Authorization: Basic c3ByaW5nLWJvb3Qtc3ByaW5nLWJvb3Qtc3ByaW5nLWJvb3Q6
|
||
|
||
grant_type=password
|
||
&username=admin
|
||
&password=123456
|
||
&scope=server
|
||
|
||
### 手机号密码登录（新增）
|
||
POST /oauth2/token
|
||
Content-Type: application/x-www-form-urlencoded
|
||
Authorization: Basic c3ByaW5nLWJvb3Qtc3ByaW5nLWJvb3Qtc3ByaW5nLWJvb3Q6
|
||
|
||
grant_type=password
|
||
&account=13800138000
|
||
&accountType=PHONE
|
||
&password=123456
|
||
&scope=server
|
||
|
||
### 邮箱密码登录（新增）
|
||
POST /oauth2/token
|
||
Content-Type: application/x-www-form-urlencoded
|
||
Authorization: Basic c3ByaW5nLWJvb3Qtc3ByaW5nLWJvb3Qtc3ByaW5nLWJvb3Q6
|
||
|
||
grant_type=password
|
||
&account=user@example.com
|
||
&accountType=EMAIL
|
||
&password=123456
|
||
&scope=server
|
||
```
|
||
|
||
### 7.2 短信登录
|
||
|
||
```http
|
||
### 短信验证码登录
|
||
POST /oauth2/token
|
||
Content-Type: application/x-www-form-urlencoded
|
||
Authorization: Basic c3ByaW5nLWJvb3Qtc3ByaW5nLWJvb3Qtc3ByaW5nLWJvb3Q6
|
||
|
||
grant_type=sms
|
||
&phone=13800138000
|
||
&code=123456
|
||
&scope=server
|
||
```
|
||
|
||
### 7.3 微信登录
|
||
|
||
```http
|
||
### 微信登录
|
||
POST /oauth2/token
|
||
Content-Type: application/x-www-form-urlencoded
|
||
Authorization: Basic c3ByaW5nLWJvb3Qtc3ByaW5nLWJvb3Qtc3ByaW5nLWJvb3Q6
|
||
|
||
grant_type=wechat
|
||
&code=wx_auth_code_xxx
|
||
&phone=13800138000
|
||
&scope=server
|
||
```
|
||
|
||
### 7.4 支付宝登录
|
||
|
||
```http
|
||
### 支付宝登录
|
||
POST /oauth2/token
|
||
Content-Type: application/x-www-form-urlencoded
|
||
Authorization: Basic c3ByaW5nLWJvb3Qtc3ByaW5nLWJvb3Qtc3ByaW5nLWJvb3Q6
|
||
|
||
grant_type=alipay
|
||
&code=alipay_auth_code_xxx
|
||
&phone=13800138000
|
||
&scope=server
|
||
```
|
||
|
||
### 7.5 响应格式
|
||
|
||
所有登录方式返回统一的 OAuth2 Token 响应：
|
||
|
||
```json
|
||
{
|
||
"access_token": "abc123...",
|
||
"token_type": "Bearer",
|
||
"expires_in": 7200,
|
||
"refresh_token": "def456...",
|
||
"scope": "server"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 8. 配置设计
|
||
|
||
### 8.1 微信配置
|
||
|
||
```yaml
|
||
# Nacos 配置：rui-service-auth.yaml 或 rui-common.yaml
|
||
social:
|
||
wechat:
|
||
app-id: wx1234567890abcdef
|
||
app-secret: your-app-secret
|
||
# 可选：token 刷新地址
|
||
token-url: https://api.weixin.qq.com/sns/oauth2/access_token
|
||
# 可选：用户信息地址
|
||
user-info-url: https://api.weixin.qq.com/sns/userinfo
|
||
```
|
||
|
||
### 8.2 支付宝配置
|
||
|
||
```yaml
|
||
social:
|
||
alipay:
|
||
app-id: 2024XXXXXXXXXXXX
|
||
private-key: your-private-key
|
||
public-key: alipay-public-key
|
||
# 可选：网关地址
|
||
gateway-url: https://openapi.alipay.com/gateway.do
|
||
```
|
||
|
||
### 8.3 客户端授权类型配置
|
||
|
||
修改 `sys_oauth_client` 表，为客户端添加新的授权类型：
|
||
|
||
```sql
|
||
-- 更新默认客户端，支持所有登录方式
|
||
UPDATE sys_oauth_client
|
||
SET grant_types = 'password,refresh_token,client_credentials,sms,wechat,alipay'
|
||
WHERE client_id = 'rui-client';
|
||
```
|
||
|
||
---
|
||
|
||
## 9. 安全设计
|
||
|
||
### 9.1 验证码安全
|
||
|
||
- 短信验证码有效期：5 分钟
|
||
- 验证码错误次数限制：5 次/小时
|
||
- 验证码存储：Redis，key = `sms:code:{phone}`
|
||
|
||
### 9.2 第三方登录安全
|
||
|
||
- 微信/支付宝授权码只能使用一次
|
||
- 授权码有效期：5 分钟（由微信/支付宝平台控制）
|
||
- 后端必须校验授权码的真实性（调平台 API）
|
||
|
||
### 9.3 密码安全
|
||
|
||
- 第三方登录自动创建的用户，生成随机密码（32 位随机字符串）
|
||
- 用户首次设置密码时，要求提供原密码或通过手机验证码验证
|
||
|
||
---
|
||
|
||
## 10. 错误码设计
|
||
|
||
| 错误码 | 描述 | 场景 |
|
||
|-------|------|------|
|
||
| `invalid_request` | 请求参数错误 | 缺少必填参数、参数格式错误 |
|
||
| `invalid_grant` | 授权失败 | 验证码错误、授权码无效 |
|
||
| `invalid_client` | 客户端认证失败 | 客户端不存在、授权类型不支持 |
|
||
| `unauthorized_client` | 客户端未授权 | 客户端不支持该授权类型 |
|
||
| `server_error` | 服务器内部错误 | 调用第三方 API 失败 |
|
||
|
||
---
|
||
|
||
## 11. 测试策略
|
||
|
||
### 11.1 单元测试
|
||
|
||
- `PasswordAuthenticationConverterTest`: 测试参数提取和校验
|
||
- `SmsAuthenticationProviderTest`: 测试验证码校验逻辑
|
||
- `WechatAuthenticationProviderTest`: Mock 微信 API，测试用户创建流程
|
||
|
||
### 11.2 集成测试
|
||
|
||
- 使用 H2 内存数据库测试完整登录流程
|
||
- 使用 WireMock 模拟微信/支付宝 API
|
||
|
||
### 11.3 手动测试清单
|
||
|
||
- [ ] 用户名密码登录（兼容测试）
|
||
- [ ] 手机号密码登录
|
||
- [ ] 邮箱密码登录
|
||
- [ ] 短信验证码登录（使用 Redis 手动设置验证码）
|
||
- [ ] 微信登录（使用测试授权码）
|
||
- [ ] 支付宝登录（使用测试授权码）
|
||
- [ ] 第三方登录后绑定手机号
|
||
- [ ] 同一微信不同手机号创建不同用户
|
||
- [ ] unionId 优先查询验证
|
||
|
||
---
|
||
|
||
## 12. 风险与回滚
|
||
|
||
### 12.1 风险
|
||
|
||
| 风险 | 影响 | 缓解措施 |
|
||
|------|------|---------|
|
||
| 微信/支付宝 API 变更 | 登录失败 | 封装 API 调用，便于快速适配 |
|
||
| 手机号重复 | 数据不一致 | 数据库唯一索引 + 代码校验 |
|
||
| 性能问题 | 登录慢 | Redis 缓存 + 异步记录日志 |
|
||
|
||
### 12.2 回滚方案
|
||
|
||
- 数据库变更：保留原字段，新增字段不影响现有数据
|
||
- 代码回滚：新授权模式独立实现，不影响现有 `password` 模式
|
||
- 配置回滚：移除新 grant_type 即可禁用
|
||
|
||
---
|
||
|
||
## 13. 后续优化
|
||
|
||
1. **短信服务商接入**：实现真实的短信发送功能
|
||
2. **社交账号解绑**：提供 API 解除第三方绑定
|
||
3. **多账号合并**：支持将多个第三方账号合并到同一用户
|
||
4. **登录设备管理**：记录登录设备，支持远程登出
|
||
5. **扫码登录**：支持微信扫码登录 PC 端
|
||
|
||
---
|
||
|
||
## 14. 附录
|
||
|
||
### 14.1 登录类型枚举
|
||
|
||
```java
|
||
public enum LoginType {
|
||
PASSWORD(1, "密码登录"),
|
||
SMS(2, "短信登录"),
|
||
WECHAT(3, "微信登录"),
|
||
ALIPAY(4, "支付宝登录");
|
||
|
||
private final int code;
|
||
private final String description;
|
||
|
||
LoginType(int code, String description) {
|
||
this.code = code;
|
||
this.description = description;
|
||
}
|
||
}
|
||
```
|
||
|
||
### 14.2 账号类型枚举
|
||
|
||
```java
|
||
public enum AccountType {
|
||
USERNAME("用户名"),
|
||
PHONE("手机号"),
|
||
EMAIL("邮箱");
|
||
|
||
private final String description;
|
||
|
||
AccountType(String description) {
|
||
this.description = description;
|
||
}
|
||
}
|
||
```
|
||
|
||
### 14.3 第三方平台枚举
|
||
|
||
```java
|
||
public enum SocialProvider {
|
||
WECHAT("微信"),
|
||
ALIPAY("支付宝");
|
||
|
||
private final String description;
|
||
|
||
SocialProvider(String description) {
|
||
this.description = description;
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
**文档结束**
|