feat(auth): 添加二维码登录功能- 实现了二维码登录的前端组件和API接口
- 添加了二维码登录的后端逻辑和数据库设计 - 编写了详细的使用说明和接口文档 - 提供了演示页面和测试工具
This commit is contained in:
262
docs/qr-login-setup-guide.md
Normal file
262
docs/qr-login-setup-guide.md
Normal file
@@ -0,0 +1,262 @@
|
||||
# 二维码登录功能设置指南
|
||||
|
||||
## 概述
|
||||
|
||||
本指南将帮助您设置和测试二维码登录功能。后端Java代码已经完成，前端Vue代码已经适配完成。
|
||||
|
||||
## 🎯 功能状态
|
||||
|
||||
- ✅ **后端实现**: Java Spring Boot (已完成)
|
||||
- ✅ **前端适配**: Vue 3 + TypeScript (已完成)
|
||||
- ✅ **接口对接**: API接口已适配
|
||||
- ✅ **测试页面**: 提供完整的测试工具
|
||||
|
||||
## 🚀 快速开始
|
||||
|
||||
### 1. 启动后端服务
|
||||
|
||||
确保您的Java后端服务正在运行，并且包含以下文件：
|
||||
|
||||
```
|
||||
java/auto/
|
||||
├── controller/QrLoginController.java
|
||||
├── service/QrLoginService.java
|
||||
├── service/impl/QrLoginServiceImpl.java
|
||||
└── dto/
|
||||
├── QrLoginGenerateResponse.java
|
||||
├── QrLoginStatusResponse.java
|
||||
├── QrLoginConfirmRequest.java
|
||||
└── QrLoginData.java
|
||||
```
|
||||
|
||||
### 2. 启动前端服务
|
||||
|
||||
```bash
|
||||
npm run dev
|
||||
# 或
|
||||
yarn dev
|
||||
```
|
||||
|
||||
### 3. 测试接口连通性
|
||||
|
||||
访问接口测试页面：
|
||||
```
|
||||
http://localhost:3000/qr-test
|
||||
```
|
||||
|
||||
按照以下步骤测试：
|
||||
|
||||
1. **生成二维码** - 点击"生成二维码"按钮
|
||||
2. **检查状态** - 开启"自动检查"开关
|
||||
3. **模拟扫码** - 点击"模拟扫码"按钮
|
||||
4. **确认登录** - 输入用户ID，点击"确认登录"
|
||||
|
||||
## 📱 使用流程
|
||||
|
||||
### Web端操作
|
||||
|
||||
1. **进入登录页面**
|
||||
```
|
||||
http://localhost:3000/login
|
||||
```
|
||||
|
||||
2. **切换到扫码登录**
|
||||
- 点击右上角的二维码图标
|
||||
- 系统自动生成二维码
|
||||
|
||||
3. **等待扫码**
|
||||
- 二维码有效期5分钟
|
||||
- 系统每2秒检查一次状态
|
||||
|
||||
### 移动端操作
|
||||
|
||||
1. **扫描二维码**
|
||||
- 使用手机扫描Web端的二维码
|
||||
- 或直接访问二维码中的URL
|
||||
|
||||
2. **确认登录**
|
||||
```
|
||||
http://localhost:3000/qr-confirm?qrCodeKey=abc123def456
|
||||
```
|
||||
- 显示用户信息和设备信息
|
||||
- 点击"确认登录"完成登录
|
||||
|
||||
## 🔧 配置说明
|
||||
|
||||
### 后端配置
|
||||
|
||||
在 `application.yml` 中配置JWT相关参数：
|
||||
|
||||
```yaml
|
||||
config:
|
||||
jwt:
|
||||
secret: websoft-jwt-secret-key-2025
|
||||
expire: 86400 # 24小时
|
||||
```
|
||||
|
||||
### 前端配置
|
||||
|
||||
在 `src/config/setting.ts` 中确认API地址：
|
||||
|
||||
```typescript
|
||||
export const SERVER_API_URL = 'http://localhost:8080';
|
||||
```
|
||||
|
||||
## 🧪 测试场景
|
||||
|
||||
### 1. 正常登录流程
|
||||
|
||||
1. Web端生成二维码
|
||||
2. 移动端扫码
|
||||
3. 移动端确认登录
|
||||
4. Web端自动登录成功
|
||||
|
||||
### 2. 过期场景
|
||||
|
||||
1. 生成二维码后等待5分钟
|
||||
2. 二维码自动过期
|
||||
3. 点击刷新重新生成
|
||||
|
||||
### 3. 取消场景
|
||||
|
||||
1. 移动端扫码后点击取消
|
||||
2. Web端继续等待新的扫码
|
||||
|
||||
## 🔍 调试方法
|
||||
|
||||
### 1. 查看网络请求
|
||||
|
||||
打开浏览器开发者工具 → Network面板：
|
||||
|
||||
- `POST /api/qr-login/generate` - 生成二维码
|
||||
- `GET /api/qr-login/status/{token}` - 检查状态
|
||||
- `POST /api/qr-login/scan/{token}` - 扫码标记
|
||||
- `POST /api/qr-login/confirm` - 确认登录
|
||||
|
||||
### 2. 查看控制台日志
|
||||
|
||||
前端会输出详细的调试信息：
|
||||
|
||||
```javascript
|
||||
// 开启调试模式
|
||||
localStorage.setItem('debug', 'qr-login');
|
||||
```
|
||||
|
||||
### 3. 后端日志
|
||||
|
||||
查看后端控制台输出：
|
||||
|
||||
```
|
||||
生成扫码登录token: abc123def456
|
||||
用户 admin 确认扫码登录，token: abc123def456
|
||||
扫码登录token abc123def456 状态更新为已扫码
|
||||
```
|
||||
|
||||
## 🛠️ 常见问题
|
||||
|
||||
### 1. 二维码生成失败
|
||||
|
||||
**可能原因：**
|
||||
- 后端服务未启动
|
||||
- Redis服务未启动
|
||||
- 网络连接问题
|
||||
|
||||
**解决方法：**
|
||||
- 检查后端服务状态
|
||||
- 确认Redis连接正常
|
||||
- 查看控制台错误信息
|
||||
|
||||
### 2. 扫码后无响应
|
||||
|
||||
**可能原因：**
|
||||
- 二维码已过期
|
||||
- 用户未登录
|
||||
- 网络请求失败
|
||||
|
||||
**解决方法：**
|
||||
- 刷新二维码
|
||||
- 确认用户登录状态
|
||||
- 检查网络连接
|
||||
|
||||
### 3. 确认登录失败
|
||||
|
||||
**可能原因：**
|
||||
- 用户ID不存在
|
||||
- 用户状态异常
|
||||
- JWT配置错误
|
||||
|
||||
**解决方法：**
|
||||
- 检查用户数据
|
||||
- 确认用户状态正常
|
||||
- 验证JWT配置
|
||||
|
||||
## 📋 API接口清单
|
||||
|
||||
| 接口 | 方法 | 路径 | 说明 |
|
||||
|------|------|------|------|
|
||||
| 生成二维码 | POST | `/api/qr-login/generate` | 生成登录二维码 |
|
||||
| 检查状态 | GET | `/api/qr-login/status/{token}` | 检查二维码状态 |
|
||||
| 扫码标记 | POST | `/api/qr-login/scan/{token}` | 标记已扫码 |
|
||||
| 确认登录 | POST | `/api/qr-login/confirm` | 确认登录 |
|
||||
| 微信确认 | POST | `/api/qr-login/wechat-confirm` | 微信小程序确认 |
|
||||
|
||||
## 🔐 安全特性
|
||||
|
||||
1. **时效控制**: 二维码5分钟自动过期
|
||||
2. **一次性使用**: 每个二维码只能使用一次
|
||||
3. **状态验证**: 严格的状态流转控制
|
||||
4. **JWT安全**: 使用JWT进行身份验证
|
||||
5. **Redis存储**: 使用Redis存储临时数据
|
||||
|
||||
## 📈 性能优化
|
||||
|
||||
1. **轮询间隔**: 前端每2秒检查一次状态
|
||||
2. **缓存策略**: Redis自动过期清理
|
||||
3. **并发控制**: 支持多用户同时使用
|
||||
4. **资源清理**: 及时清理过期数据
|
||||
|
||||
## 🎨 自定义配置
|
||||
|
||||
### 修改过期时间
|
||||
|
||||
在后端常量中修改：
|
||||
|
||||
```java
|
||||
// 默认5分钟 = 300秒
|
||||
private static final Long QR_LOGIN_TOKEN_TTL = 300L;
|
||||
```
|
||||
|
||||
### 修改检查间隔
|
||||
|
||||
在前端组件中修改：
|
||||
|
||||
```typescript
|
||||
// 默认2秒检查一次
|
||||
}, 2000);
|
||||
```
|
||||
|
||||
### 修改二维码样式
|
||||
|
||||
在前端组件中修改：
|
||||
|
||||
```vue
|
||||
<ele-qr-code-svg :value="qrCodeData" :size="200" />
|
||||
```
|
||||
|
||||
## 📞 技术支持
|
||||
|
||||
如果遇到问题，请：
|
||||
|
||||
1. 查看控制台错误信息
|
||||
2. 检查网络请求状态
|
||||
3. 确认后端服务正常
|
||||
4. 查看本文档的常见问题部分
|
||||
|
||||
## 🔄 更新日志
|
||||
|
||||
### v1.0.0 (当前版本)
|
||||
- ✅ 完成后端Java实现
|
||||
- ✅ 完成前端Vue适配
|
||||
- ✅ 提供完整测试工具
|
||||
- ✅ 支持Web端和移动端
|
||||
- ✅ 支持微信小程序登录
|
||||
Reference in New Issue
Block a user