feat(auth): 添加二维码登录功能- 实现了二维码登录的前端组件和API接口
- 添加了二维码登录的后端逻辑和数据库设计 - 编写了详细的使用说明和接口文档 - 提供了演示页面和测试工具
This commit is contained in:
234
docs/qr-login-usage.md
Normal file
234
docs/qr-login-usage.md
Normal file
@@ -0,0 +1,234 @@
|
||||
# 二维码登录功能使用说明
|
||||
|
||||
## 功能概述
|
||||
|
||||
二维码登录功能为用户提供了一种便捷的登录方式，用户可以通过手机APP或小程序扫描Web端生成的二维码来快速登录管理后台，无需输入用户名和密码。
|
||||
|
||||
## 功能特点
|
||||
|
||||
1. **便捷性**：无需输入账号密码，扫码即可登录
|
||||
2. **安全性**：二维码具有时效性，过期自动失效
|
||||
3. **实时性**：支持实时状态更新，用户体验流畅
|
||||
4. **跨平台**：支持APP和小程序扫码登录
|
||||
|
||||
## 使用流程
|
||||
|
||||
### Web端操作流程
|
||||
|
||||
1. **进入登录页面**
|
||||
- 访问系统登录页面
|
||||
- 点击右上角的二维码图标切换到扫码登录模式
|
||||
|
||||
2. **生成二维码**
|
||||
- 系统自动生成登录二维码
|
||||
- 二维码有效期为5分钟
|
||||
|
||||
3. **等待扫码**
|
||||
- 使用手机APP或小程序扫描二维码
|
||||
- 系统实时检测扫码状态
|
||||
|
||||
4. **完成登录**
|
||||
- 用户在手机端确认登录后，Web端自动完成登录
|
||||
- 跳转到系统首页
|
||||
|
||||
### 移动端操作流程
|
||||
|
||||
1. **扫描二维码**
|
||||
- 打开手机APP或小程序
|
||||
- 使用扫码功能扫描Web端的二维码
|
||||
|
||||
2. **确认登录**
|
||||
- 跳转到登录确认页面
|
||||
- 显示用户信息和设备信息
|
||||
- 点击"确认登录"按钮
|
||||
|
||||
3. **完成登录**
|
||||
- 系统完成登录验证
|
||||
- Web端自动登录成功
|
||||
|
||||
## 组件使用
|
||||
|
||||
### 在登录页面中集成
|
||||
|
||||
```vue
|
||||
<template>
|
||||
<div v-if="loginType === 'scan'">
|
||||
<QrLogin
|
||||
@loginSuccess="onQrLoginSuccess"
|
||||
@loginError="onQrLoginError"
|
||||
/>
|
||||
</div>
|
||||
</template>
|
||||
|
||||
<script setup>
|
||||
import QrLogin from '@/components/QrLogin/index.vue';
|
||||
|
||||
const onQrLoginSuccess = (token) => {
|
||||
// 处理登录成功
|
||||
localStorage.setItem('access_token', token);
|
||||
// 跳转到首页
|
||||
router.push('/');
|
||||
};
|
||||
|
||||
const onQrLoginError = (error) => {
|
||||
// 处理登录错误
|
||||
message.error(error);
|
||||
};
|
||||
</script>
|
||||
```
|
||||
|
||||
### 独立使用二维码组件
|
||||
|
||||
```vue
|
||||
<template>
|
||||
<QrLogin
|
||||
@loginSuccess="handleLoginSuccess"
|
||||
@loginError="handleLoginError"
|
||||
/>
|
||||
</template>
|
||||
|
||||
<script setup>
|
||||
import QrLogin from '@/components/QrLogin/index.vue';
|
||||
|
||||
const handleLoginSuccess = (token) => {
|
||||
console.log('登录成功，token:', token);
|
||||
};
|
||||
|
||||
const handleLoginError = (error) => {
|
||||
console.error('登录失败:', error);
|
||||
};
|
||||
</script>
|
||||
```
|
||||
|
||||
## API接口
|
||||
|
||||
### 前端API调用
|
||||
|
||||
```typescript
|
||||
import {
|
||||
generateQrCode,
|
||||
checkQrCodeStatus,
|
||||
confirmQrLogin,
|
||||
cancelQrLogin
|
||||
} from '@/api/passport/qrLogin';
|
||||
|
||||
// 生成二维码
|
||||
const qrData = await generateQrCode();
|
||||
|
||||
// 检查状态
|
||||
const status = await checkQrCodeStatus(qrCodeKey);
|
||||
|
||||
// 确认登录（移动端）
|
||||
await confirmQrLogin(qrCodeKey, userToken);
|
||||
|
||||
// 取消登录（移动端）
|
||||
await cancelQrLogin(qrCodeKey);
|
||||
```
|
||||
|
||||
## 状态说明
|
||||
|
||||
| 状态 | 说明 | 显示内容 |
|
||||
|------|------|----------|
|
||||
| loading | 正在生成二维码 | 加载动画 + "正在生成二维码..." |
|
||||
| active | 二维码有效，等待扫码 | 二维码 + "请使用手机APP或小程序扫码登录" |
|
||||
| scanned | 已扫码，等待确认 | 成功图标 + "扫码成功，请在手机上确认登录" |
|
||||
| expired | 二维码已过期 | 过期图标 + "二维码已过期" + 刷新按钮 |
|
||||
| error | 生成失败 | 错误图标 + 错误信息 + 重新生成按钮 |
|
||||
|
||||
## 配置说明
|
||||
|
||||
### 二维码配置
|
||||
|
||||
```typescript
|
||||
// 二维码大小
|
||||
const qrCodeSize = 200; // 像素
|
||||
|
||||
// 过期时间
|
||||
const expireTime = 300; // 5分钟
|
||||
|
||||
// 检查间隔
|
||||
const checkInterval = 2000; // 2秒
|
||||
```
|
||||
|
||||
### 样式自定义
|
||||
|
||||
```less
|
||||
// 自定义二维码容器样式
|
||||
.qr-login-container {
|
||||
padding: 20px;
|
||||
text-align: center;
|
||||
|
||||
.qr-code-wrapper {
|
||||
min-height: 250px;
|
||||
display: flex;
|
||||
flex-direction: column;
|
||||
align-items: center;
|
||||
justify-content: center;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 安全注意事项
|
||||
|
||||
1. **二维码时效性**
|
||||
- 二维码默认5分钟过期
|
||||
- 过期后需要重新生成
|
||||
|
||||
2. **一次性使用**
|
||||
- 每个二维码只能使用一次
|
||||
- 登录成功或取消后立即失效
|
||||
|
||||
3. **用户验证**
|
||||
- 移动端需要用户已登录状态
|
||||
- 验证用户身份后才能确认登录
|
||||
|
||||
4. **网络安全**
|
||||
- 使用HTTPS协议传输
|
||||
- 敏感信息加密处理
|
||||
|
||||
## 故障排除
|
||||
|
||||
### 常见问题
|
||||
|
||||
1. **二维码生成失败**
|
||||
- 检查网络连接
|
||||
- 确认后端API接口正常
|
||||
- 查看浏览器控制台错误信息
|
||||
|
||||
2. **扫码后无响应**
|
||||
- 检查移动端网络连接
|
||||
- 确认二维码未过期
|
||||
- 检查用户登录状态
|
||||
|
||||
3. **登录确认失败**
|
||||
- 检查用户权限
|
||||
- 确认token有效性
|
||||
- 查看后端日志
|
||||
|
||||
### 调试方法
|
||||
|
||||
1. **开启控制台调试**
|
||||
```javascript
|
||||
// 在浏览器控制台查看详细日志
|
||||
localStorage.setItem('debug', 'qr-login');
|
||||
```
|
||||
|
||||
2. **网络请求监控**
|
||||
- 使用浏览器开发者工具监控网络请求
|
||||
- 检查API响应状态和数据
|
||||
|
||||
3. **状态跟踪**
|
||||
- 观察二维码状态变化
|
||||
- 记录状态转换时间点
|
||||
|
||||
## 更新日志
|
||||
|
||||
### v1.0.0
|
||||
- 初始版本发布
|
||||
- 支持基本的二维码登录功能
|
||||
- 包含Web端和移动端完整流程
|
||||
|
||||
### 后续计划
|
||||
- 支持多设备同时登录
|
||||
- 添加登录设备管理
|
||||
- 优化用户体验和界面设计
|
||||
Reference in New Issue
Block a user