mp-vue/docs/qr-login-setup-guide.md

二维码登录功能设置指南

概述

本指南将帮助您设置和测试二维码登录功能。后端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. 启动前端服务

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相关参数：

config:
  jwt:
    secret: websoft-jwt-secret-key-2025
    expire: 86400  # 24小时

前端配置

在 src/config/setting.ts 中确认API地址：

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. 查看控制台日志

前端会输出详细的调试信息：

// 开启调试模式
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. 资源清理: 及时清理过期数据

🎨 自定义配置

修改过期时间

在后端常量中修改：

// 默认5分钟 = 300秒
private static final Long QR_LOGIN_TOKEN_TTL = 300L;

修改检查间隔

在前端组件中修改：

// 默认2秒检查一次
}, 2000);

修改二维码样式

在前端组件中修改：

<ele-qr-code-svg :value="qrCodeData" :size="200" />

📞 技术支持

如果遇到问题，请：

1. 查看控制台错误信息
2. 检查网络请求状态
3. 确认后端服务正常
4. 查看本文档的常见问题部分

🔄 更新日志

v1.0.0 (当前版本)

• ✅ 完成后端Java实现
• ✅ 完成前端Vue适配
• ✅ 提供完整测试工具
• ✅ 支持Web端和移动端
• ✅ 支持微信小程序登录