mp-vue/docs/qr-login-usage.md

二维码登录功能使用说明

功能概述

二维码登录功能为用户提供了一种便捷的登录方式，用户可以通过手机APP或小程序扫描Web端生成的二维码来快速登录管理后台，无需输入用户名和密码。

功能特点

1. 便捷性：无需输入账号密码，扫码即可登录
2. 安全性：二维码具有时效性，过期自动失效
3. 实时性：支持实时状态更新，用户体验流畅
4. 跨平台：支持APP和小程序扫码登录

使用流程

Web端操作流程

1. 进入登录页面

   • 访问系统登录页面
   • 点击右上角的二维码图标切换到扫码登录模式

2. 生成二维码

   • 系统自动生成登录二维码
   • 二维码有效期为5分钟

3. 等待扫码

   • 使用手机APP或小程序扫描二维码
   • 系统实时检测扫码状态

4. 完成登录

   • 用户在手机端确认登录后，Web端自动完成登录
   • 跳转到系统首页

移动端操作流程

1. 扫描二维码

   • 打开手机APP或小程序
   • 使用扫码功能扫描Web端的二维码

2. 确认登录

   • 跳转到登录确认页面
   • 显示用户信息和设备信息
   • 点击"确认登录"按钮

3. 完成登录

   • 系统完成登录验证
   • Web端自动登录成功

组件使用

在登录页面中集成

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

独立使用二维码组件

<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调用

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	生成失败	错误图标 + 错误信息 + 重新生成按钮

配置说明

二维码配置

// 二维码大小
const qrCodeSize = 200; // 像素

// 过期时间
const expireTime = 300; // 5分钟

// 检查间隔
const checkInterval = 2000; // 2秒

样式自定义

// 自定义二维码容器样式
.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. 开启控制台调试

   // 在浏览器控制台查看详细日志
   localStorage.setItem('debug', 'qr-login');
   

2. 网络请求监控

   • 使用浏览器开发者工具监控网络请求
   • 检查API响应状态和数据

3. 状态跟踪

   • 观察二维码状态变化
   • 记录状态转换时间点

更新日志

v1.0.0

• 初始版本发布
• 支持基本的二维码登录功能
• 包含Web端和移动端完整流程

后续计划

• 支持多设备同时登录
• 添加登录设备管理
• 优化用户体验和界面设计