263 lines
5.4 KiB
Markdown
263 lines
5.4 KiB
Markdown
# 二维码登录功能设置指南
|
||
|
||
## 概述
|
||
|
||
本指南将帮助您设置和测试二维码登录功能。后端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端和移动端
|
||
- ✅ 支持微信小程序登录
|