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端自动登录成功

## 组件使用

### 在登录页面中集成

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

### 独立使用二维码组件

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

## API接口

### 前端API调用

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

## 配置说明

### 二维码配置

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

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

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

### 样式自定义

```less
// 自定义二维码容器样式
.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. **开启控制台调试**
   ```javascript
   // 在浏览器控制台查看详细日志
   localStorage.setItem('debug', 'qr-login');
   ```

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

3. **状态跟踪**
   - 观察二维码状态变化
   - 记录状态转换时间点

## 更新日志

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

### 后续计划
- 支持多设备同时登录
- 添加登录设备管理
- 优化用户体验和界面设计