# 二维码登录功能设置指南

## 概述

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