213 lines
4.7 KiB
Markdown
213 lines
4.7 KiB
Markdown
# 二维码登录API接口文档（已适配后端）
|
||
|
||
## 概述
|
||
|
||
二维码登录功能允许用户通过手机APP或小程序扫描Web端生成的二维码来完成登录，提供更便捷和安全的登录体验。
|
||
|
||
**后端实现状态：** ✅ 已完成
|
||
**前端适配状态：** ✅ 已完成
|
||
|
||
## 接口列表
|
||
|
||
### 1. 生成登录二维码
|
||
|
||
**接口地址：** `POST /api/qr-login/generate`
|
||
|
||
**请求参数：** 无
|
||
|
||
**响应数据：**
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"message": "生成成功",
|
||
"data": {
|
||
"token": "abc123def456",
|
||
"qrCode": "qr-login:abc123def456",
|
||
"expiresIn": 300
|
||
}
|
||
}
|
||
```
|
||
|
||
**字段说明：**
|
||
- `token`: 二维码唯一标识token，用于后续状态查询
|
||
- `qrCode`: 二维码内容（后端生成的原始内容）
|
||
- `expiresIn`: 过期时间（秒），默认300秒（5分钟）
|
||
|
||
### 2. 检查二维码状态
|
||
|
||
**接口地址：** `GET /api/qr-login/status/{token}`
|
||
|
||
**请求参数：**
|
||
- `token`: 二维码token（路径参数）
|
||
|
||
**响应数据：**
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"message": "查询成功",
|
||
"data": {
|
||
"status": "pending",
|
||
"expiresIn": 280
|
||
}
|
||
}
|
||
```
|
||
|
||
**状态说明：**
|
||
- `pending`: 等待扫码
|
||
- `scanned`: 已扫码，等待确认
|
||
- `confirmed`: 已确认登录
|
||
- `expired`: 已过期
|
||
|
||
**登录成功时的响应：**
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"message": "登录成功",
|
||
"data": {
|
||
"status": "confirmed",
|
||
"accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
|
||
"userInfo": {
|
||
"userId": 1,
|
||
"username": "admin",
|
||
"nickname": "管理员",
|
||
"avatar": "https://example.com/avatar.jpg"
|
||
},
|
||
"expiresIn": 60
|
||
}
|
||
}
|
||
```
|
||
|
||
### 3. 扫码标记
|
||
|
||
**接口地址：** `POST /api/qr-login/scan/{token}`
|
||
|
||
**请求参数：**
|
||
- `token`: 二维码token（路径参数）
|
||
|
||
**响应数据：**
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"message": "操作成功",
|
||
"data": true
|
||
}
|
||
```
|
||
|
||
### 4. 确认登录
|
||
|
||
**接口地址：** `POST /api/qr-login/confirm`
|
||
|
||
**请求参数：**
|
||
```json
|
||
{
|
||
"token": "abc123def456",
|
||
"userId": 1,
|
||
"platform": "web"
|
||
}
|
||
```
|
||
|
||
**响应数据：**
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"message": "确认成功",
|
||
"data": {
|
||
"status": "confirmed",
|
||
"accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
|
||
"userInfo": {
|
||
"userId": 1,
|
||
"username": "admin",
|
||
"nickname": "管理员"
|
||
},
|
||
"expiresIn": 60
|
||
}
|
||
}
|
||
```
|
||
|
||
### 5. 微信小程序确认登录
|
||
|
||
**接口地址：** `POST /api/qr-login/wechat-confirm`
|
||
|
||
**请求参数：**
|
||
```json
|
||
{
|
||
"token": "abc123def456",
|
||
"userId": 1,
|
||
"platform": "miniprogram",
|
||
"wechatInfo": {
|
||
"openid": "wx_openid_123",
|
||
"unionid": "wx_unionid_456",
|
||
"nickname": "微信用户",
|
||
"avatar": "https://wx.qlogo.cn/..."
|
||
}
|
||
}
|
||
```
|
||
|
||
**响应数据：**
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"message": "微信小程序登录确认成功",
|
||
"data": {
|
||
"status": "confirmed",
|
||
"accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
|
||
"userInfo": {...},
|
||
"expiresIn": 60
|
||
}
|
||
}
|
||
```
|
||
|
||
## 实现流程
|
||
|
||
### Web端流程：
|
||
1. 用户点击扫码登录
|
||
2. 前端调用 `/qr-login/generate` 生成二维码
|
||
3. 显示二维码给用户
|
||
4. 前端轮询调用 `/qr-login/status` 检查状态
|
||
5. 当状态为 `confirmed` 时，获取token完成登录
|
||
|
||
### 移动端流程：
|
||
1. 用户扫描二维码，跳转到确认页面
|
||
2. 页面加载时调用 `/qr-login/scan` 标记已扫码
|
||
3. 用户点击确认后调用 `/qr-login/confirm` 确认登录
|
||
4. 或用户点击取消后调用 `/qr-login/cancel` 取消登录
|
||
|
||
## 安全考虑
|
||
|
||
1. **二维码有效期**：建议设置5分钟有效期，过期后需要重新生成
|
||
2. **一次性使用**：每个二维码只能使用一次，确认或取消后立即失效
|
||
3. **用户验证**：移动端需要验证用户的登录状态
|
||
4. **IP限制**：可以记录生成二维码的IP，限制异地登录
|
||
5. **频率限制**：限制同一IP生成二维码的频率
|
||
|
||
## 数据库设计建议
|
||
|
||
```sql
|
||
CREATE TABLE qr_login_records (
|
||
id BIGINT PRIMARY KEY AUTO_INCREMENT,
|
||
qr_code_key VARCHAR(64) UNIQUE NOT NULL COMMENT '二维码唯一标识',
|
||
status ENUM('waiting', 'scanned', 'confirmed', 'expired', 'cancelled') DEFAULT 'waiting' COMMENT '状态',
|
||
user_id BIGINT NULL COMMENT '扫码用户ID',
|
||
client_ip VARCHAR(45) COMMENT '客户端IP',
|
||
user_agent TEXT COMMENT '用户代理',
|
||
expire_time DATETIME NOT NULL COMMENT '过期时间',
|
||
scan_time DATETIME NULL COMMENT '扫码时间',
|
||
confirm_time DATETIME NULL COMMENT '确认时间',
|
||
created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
|
||
updated_at DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
|
||
INDEX idx_qr_code_key (qr_code_key),
|
||
INDEX idx_status (status),
|
||
INDEX idx_expire_time (expire_time)
|
||
);
|
||
```
|
||
|
||
## 错误码说明
|
||
|
||
- `0`: 成功
|
||
- `400`: 参数错误
|
||
- `401`: 未授权
|
||
- `404`: 二维码不存在
|
||
- `410`: 二维码已过期
|
||
- `429`: 请求过于频繁
|
||
- `500`: 服务器内部错误
|