feat(auth): 添加二维码登录功能- 实现了二维码登录的前端组件和API接口
- 添加了二维码登录的后端逻辑和数据库设计 - 编写了详细的使用说明和接口文档 - 提供了演示页面和测试工具
This commit is contained in:
236
README-QR-LOGIN.md
Normal file
236
README-QR-LOGIN.md
Normal file
@@ -0,0 +1,236 @@
|
||||
# 二维码登录功能
|
||||
|
||||
## 概述
|
||||
|
||||
基于Vue 3 + TypeScript开发的二维码登录功能，支持APP端和小程序端扫码登录到Web管理后台。
|
||||
|
||||
## 功能特点
|
||||
|
||||
- ✅ **便捷登录**：扫码即可登录，无需输入账号密码
|
||||
- ✅ **实时状态**：支持实时状态更新和用户反馈
|
||||
- ✅ **安全可靠**：二维码具有时效性，支持一次性使用
|
||||
- ✅ **跨平台支持**：兼容APP和小程序扫码
|
||||
- ✅ **响应式设计**：适配各种屏幕尺寸
|
||||
- ✅ **TypeScript支持**：完整的类型定义
|
||||
|
||||
## 文件结构
|
||||
|
||||
```
|
||||
src/
|
||||
├── components/QrLogin/
|
||||
│ ├── index.vue # 二维码登录主组件
|
||||
│ └── demo.vue # 演示组件
|
||||
├── views/passport/
|
||||
│ ├── login/index.vue # 登录页面（已集成二维码登录）
|
||||
│ └── qrConfirm/index.vue # 移动端确认页面
|
||||
├── api/passport/
|
||||
│ └── qrLogin/index.ts # 二维码登录API
|
||||
└── router/routes.ts # 路由配置
|
||||
|
||||
docs/
|
||||
├── qr-login-api.md # API接口文档
|
||||
└── qr-login-usage.md # 使用说明文档
|
||||
```
|
||||
|
||||
## 快速开始
|
||||
|
||||
### 1. 查看演示
|
||||
|
||||
访问演示页面查看功能效果：
|
||||
```
|
||||
http://localhost:3000/qr-demo
|
||||
```
|
||||
|
||||
### 2. 在登录页面使用
|
||||
|
||||
登录页面已经集成了二维码登录功能：
|
||||
```
|
||||
http://localhost:3000/login
|
||||
```
|
||||
点击右上角的二维码图标即可切换到扫码登录模式。
|
||||
|
||||
### 3. 移动端确认页面
|
||||
|
||||
扫码后会跳转到确认页面：
|
||||
```
|
||||
http://localhost:3000/qr-confirm?qrCodeKey=xxx
|
||||
```
|
||||
|
||||
## 组件使用
|
||||
|
||||
### 基本用法
|
||||
|
||||
```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>
|
||||
```
|
||||
|
||||
### 事件说明
|
||||
|
||||
| 事件名 | 参数 | 说明 |
|
||||
|--------|------|------|
|
||||
| loginSuccess | token: string | 登录成功时触发，返回登录token |
|
||||
| loginError | error: string | 登录失败时触发，返回错误信息 |
|
||||
|
||||
## API接口
|
||||
|
||||
### 需要实现的后端接口
|
||||
|
||||
1. **生成二维码**: `POST /api/qr-login/generate`
|
||||
2. **检查状态**: `GET /api/qr-login/status`
|
||||
3. **扫码标记**: `POST /api/qr-login/scan`
|
||||
4. **确认登录**: `POST /api/qr-login/confirm`
|
||||
5. **取消登录**: `POST /api/qr-login/cancel`
|
||||
|
||||
详细的API文档请查看：[docs/qr-login-api.md](docs/qr-login-api.md)
|
||||
|
||||
## 状态流转
|
||||
|
||||
```
|
||||
loading → active → scanned → confirmed ✅
|
||||
↓ ↓ ↓
|
||||
error expired cancelled
|
||||
```
|
||||
|
||||
- **loading**: 正在生成二维码
|
||||
- **active**: 二维码有效，等待扫码
|
||||
- **scanned**: 已扫码，等待用户确认
|
||||
- **confirmed**: 用户确认，登录成功
|
||||
- **expired**: 二维码过期
|
||||
- **error**: 生成失败
|
||||
- **cancelled**: 用户取消登录
|
||||
|
||||
## 安全机制
|
||||
|
||||
1. **时效控制**：二维码默认5分钟过期
|
||||
2. **一次性使用**：每个二维码只能使用一次
|
||||
3. **状态验证**：严格的状态流转控制
|
||||
4. **用户验证**：移动端需要用户登录状态
|
||||
5. **HTTPS传输**：敏感数据加密传输
|
||||
|
||||
## 自定义配置
|
||||
|
||||
### 样式自定义
|
||||
|
||||
```less
|
||||
.qr-login-container {
|
||||
// 自定义容器样式
|
||||
padding: 20px;
|
||||
|
||||
.qr-code-wrapper {
|
||||
// 自定义二维码区域样式
|
||||
min-height: 250px;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 参数配置
|
||||
|
||||
```typescript
|
||||
// 二维码大小
|
||||
const QR_CODE_SIZE = 200;
|
||||
|
||||
// 过期时间（秒）
|
||||
const EXPIRE_TIME = 300;
|
||||
|
||||
// 状态检查间隔（毫秒）
|
||||
const CHECK_INTERVAL = 2000;
|
||||
```
|
||||
|
||||
## 开发调试
|
||||
|
||||
### 启用调试模式
|
||||
|
||||
```javascript
|
||||
// 在浏览器控制台执行
|
||||
localStorage.setItem('debug', 'qr-login');
|
||||
```
|
||||
|
||||
### 查看网络请求
|
||||
|
||||
使用浏览器开发者工具的Network面板监控API请求。
|
||||
|
||||
### 模拟测试
|
||||
|
||||
访问演示页面 `/qr-demo` 可以模拟各种状态和场景。
|
||||
|
||||
## 部署注意事项
|
||||
|
||||
1. **HTTPS要求**：生产环境必须使用HTTPS
|
||||
2. **跨域配置**：确保API接口支持跨域请求
|
||||
3. **移动端适配**：确保移动端页面正常显示
|
||||
4. **性能优化**：合理设置轮询间隔和缓存策略
|
||||
|
||||
## 故障排除
|
||||
|
||||
### 常见问题
|
||||
|
||||
1. **二维码不显示**
|
||||
- 检查网络连接
|
||||
- 确认API接口正常
|
||||
- 查看控制台错误信息
|
||||
|
||||
2. **扫码无响应**
|
||||
- 检查二维码是否过期
|
||||
- 确认移动端网络正常
|
||||
- 验证用户登录状态
|
||||
|
||||
3. **登录失败**
|
||||
- 检查token有效性
|
||||
- 确认用户权限
|
||||
- 查看后端日志
|
||||
|
||||
### 调试步骤
|
||||
|
||||
1. 打开浏览器开发者工具
|
||||
2. 查看Console面板的错误信息
|
||||
3. 监控Network面板的API请求
|
||||
4. 检查Application面板的本地存储
|
||||
|
||||
## 更新日志
|
||||
|
||||
### v1.0.0 (2024-01-XX)
|
||||
- ✅ 完成基础二维码登录功能
|
||||
- ✅ 支持实时状态更新
|
||||
- ✅ 集成到登录页面
|
||||
- ✅ 创建移动端确认页面
|
||||
- ✅ 完善文档和演示
|
||||
|
||||
## 技术栈
|
||||
|
||||
- **前端框架**: Vue 3 + TypeScript
|
||||
- **UI组件库**: Ant Design Vue
|
||||
- **二维码生成**: qrcode + ele-admin-pro
|
||||
- **状态管理**: Pinia
|
||||
- **路由管理**: Vue Router
|
||||
- **HTTP客户端**: Axios
|
||||
|
||||
## 贡献指南
|
||||
|
||||
1. Fork 项目
|
||||
2. 创建功能分支
|
||||
3. 提交代码变更
|
||||
4. 推送到分支
|
||||
5. 创建 Pull Request
|
||||
|
||||
## 许可证
|
||||
|
||||
MIT License
|
||||
Reference in New Issue
Block a user