admin-10559/README-QR-LOGIN.md

# 二维码登录功能

## 概述

基于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