template-10584/docs/QR_LOGIN_INTEGRATION.md

# 微信小程序扫码登录集成文档

## 概述

本文档介绍如何在微信小程序中集成扫码登录功能，支持用户通过小程序扫描网页端二维码快速登录。

## 功能特性

- ✅ **多平台支持** - 支持网页端、移动APP、微信小程序
- ✅ **安全可靠** - Token有效期控制，防重复使用
- ✅ **用户体验好** - 5分钟有效期，实时状态反馈
- ✅ **微信集成** - 自动获取微信用户信息
- ✅ **组件化设计** - 提供多种使用方式

## 后端接口

### 1. 生成扫码token
```
POST /api/qr-login/generate
```

### 2. 检查登录状态
```
GET /api/qr-login/status/{token}
```

### 3. 确认登录（通用）
```
POST /api/qr-login/confirm
```

### 4. 微信小程序专用确认接口
```
POST /api/qr-login/wechat-confirm
```

## 前端集成

### 1. API接口层
文件：`src/api/qr-login/index.ts`

提供了完整的扫码登录API接口封装：
- `generateQRToken()` - 生成扫码token
- `checkQRLoginStatus()` - 检查登录状态
- `confirmQRLogin()` - 确认登录
- `confirmWechatQRLogin()` - 微信小程序专用确认

### 2. Hook层
文件：`src/hooks/useQRLogin.ts`

提供了扫码登录的状态管理和业务逻辑：
```typescript
const {
  state,           // 当前状态
  error,           // 错误信息
  result,          // 登录结果
  isLoading,       // 是否加载中
  startScan,       // 开始扫码
  cancel,          // 取消扫码
  reset,           // 重置状态
  handleScanResult, // 处理扫码结果
  canScan          // 是否可以扫码
} = useQRLogin();
```

### 3. 组件层

#### QRLoginScanner 完整扫码组件
文件：`src/components/QRLoginScanner.tsx`

功能完整的扫码登录组件，包含状态显示和错误处理：
```tsx
<QRLoginScanner
  onSuccess={(result) => console.log('登录成功', result)}
  onError={(error) => console.log('登录失败', error)}
  buttonText="扫码登录"
  showStatus={true}
/>
```

#### QRLoginButton 简化按钮组件
文件：`src/components/QRLoginButton.tsx`

简化的按钮组件，支持两种模式：
```tsx
{/* 直接扫码模式 */}
<QRLoginButton
  text="扫码登录"
  onSuccess={handleSuccess}
  onError={handleError}
/>

{/* 页面跳转模式 */}
<QRLoginButton
  text="扫码登录"
  usePageMode={true}
/>
```

### 4. 页面层
文件：`src/passport/qr-login/index.tsx`

专门的扫码登录页面，提供完整的用户体验：
- 用户信息展示
- 扫码功能
- 使用说明
- 登录历史
- 安全提示

## 使用方式

### 方式一：在现有组件中集成

```tsx
import { useQRLogin } from '@/hooks/useQRLogin';

const MyComponent = () => {
  const { startScan, isLoading } = useQRLogin();
  
  const handleScan = async () => {
    try {
      await startScan();
    } catch (error) {
      console.error('扫码失败:', error);
    }
  };

  return (
    <Button loading={isLoading} onClick={handleScan}>
      扫码登录
    </Button>
  );
};
```

### 方式二：使用预制组件

```tsx
import QRLoginButton from '@/components/QRLoginButton';

const MyComponent = () => {
  return (
    <QRLoginButton
      text="扫码登录"
      usePageMode={true}
    />
  );
};
```

### 方式三：跳转到专门页面

```tsx
import Taro from '@tarojs/taro';

const handleQRLogin = () => {
  Taro.navigateTo({
    url: '/passport/qr-login/index'
  });
};
```

## 工作流程

### 网页端流程
1. 用户访问登录页面
2. 点击"扫码登录"按钮
3. 调用 `POST /api/qr-login/generate` 生成token
4. 显示包含token的二维码
5. 每2秒调用 `GET /api/qr-login/status/{token}` 检查状态
6. 状态变为 `confirmed` 时获取JWT token
7. 自动跳转到主页面

### 小程序端流程
1. 用户在小程序中点击扫码登录
2. 调用 `Taro.scanCode()` 扫描二维码
3. 解析二维码获取token
4. 调用 `POST /api/qr-login/wechat-confirm` 确认登录
5. 传递用户ID和微信用户信息
6. 显示登录确认成功提示

## 安全考虑

1. **Token有效期** - 默认5分钟有效期，防止长期暴露
2. **一次性使用** - Token确认后立即失效，防止重复使用
3. **用户确认** - 需要用户主动确认，防止误操作
4. **来源验证** - 只扫描官方网站的二维码
5. **权限检查** - 确保用户已登录小程序

## 错误处理

常见错误及处理方式：

1. **用户未登录** - 提示用户先登录小程序
2. **扫码失败** - 提示重新扫码或检查二维码
3. **Token无效** - 提示二维码已过期，请刷新
4. **网络错误** - 提示检查网络连接
5. **权限拒绝** - 引导用户开启相机权限

## 测试建议

1. **功能测试** - 测试完整的扫码登录流程
2. **异常测试** - 测试各种异常情况的处理
3. **性能测试** - 测试扫码响应速度和网络请求
4. **兼容性测试** - 测试不同设备和微信版本
5. **安全测试** - 测试Token安全性和权限控制

## 注意事项

1. 确保后端接口已正确实现
2. 配置正确的API基础URL
3. 处理好用户权限和登录状态
4. 提供清晰的用户提示和错误信息
5. 考虑网络异常和超时情况