template-10579/README_QR_LOGIN.md

# 微信小程序扫码登录功能实现

## 项目概述

本项目已完整实现微信小程序扫码登录功能，支持用户通过小程序扫描网页端二维码快速登录。

## 🎯 功能特性

- ✅ **完整的后端API** - Java Spring Boot实现
- ✅ **多种前端集成方式** - 按钮、弹窗、页面
- ✅ **智能二维码解析** - 支持URL、JSON、纯token格式
- ✅ **安全可靠** - Token有效期控制，防重复使用
- ✅ **用户体验优秀** - 实时状态反馈，错误处理完善
- ✅ **微信深度集成** - 自动获取用户信息

## 📁 项目结构

### 后端 (Java)
```
auto/
├── controller/QrLoginController.java     # REST API控制器
├── service/QrLoginService.java          # 业务接口
├── service/impl/QrLoginServiceImpl.java # 业务实现
└── dto/                                 # 数据传输对象
    ├── QrLoginData.java
    ├── QrLoginConfirmRequest.java
    ├── QrLoginStatusResponse.java
    └── QrLoginGenerateResponse.java
```

### 前端 (小程序)
```
src/
├── api/qr-login/index.ts               # API接口层
├── hooks/useQRLogin.ts                 # 业务逻辑Hook
├── components/                         # 组件层
│   ├── QRLoginButton.tsx              # 扫码按钮组件
│   ├── QRLoginScanner.tsx             # 扫码器组件
│   ├── QRScanModal.tsx                # 扫码弹窗组件
│   └── QRLoginDemo.tsx                # 演示组件
└── pages/                             # 页面层
    ├── qr-login/index.tsx             # 扫码登录页面
    ├── qr-confirm/index.tsx           # 登录确认页面
    └── qr-test/index.tsx              # 功能测试页面
```

## 🚀 快速开始

### 1. 后端配置

确保Java后端服务正常运行，API接口可访问：
- `POST /api/qr-login/generate` - 生成扫码token
- `GET /api/qr-login/status/{token}` - 检查登录状态
- `POST /api/qr-login/confirm` - 确认登录
- `POST /api/qr-login/scan/{token}` - 扫码操作

### 2. 前端使用

#### 最简单的使用方式：
```tsx
import QRLoginButton from '@/components/QRLoginButton';

<QRLoginButton />
```

#### 弹窗方式：
```tsx
import QRScanModal from '@/components/QRScanModal';

<QRScanModal
  visible={showModal}
  onClose={() => setShowModal(false)}
  onSuccess={(result) => console.log('登录成功', result)}
/>
```

#### 页面跳转方式：
```tsx
import Taro from '@tarojs/taro';

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

## 🔧 支持的二维码格式

系统智能识别多种二维码格式：

1. **URL格式**：`https://mp.websoft.top/qr-confirm?qrCodeKey=token123`
2. **JSON格式**：`{"token": "token123", "type": "qr-login"}`
3. **简单格式**：`qr-login:token123` 或直接 `token123`

## 📱 页面说明

### 1. 扫码登录页面 (`/passport/qr-login/index`)
- 完整的扫码登录功能
- 用户信息显示
- 登录历史记录
- 使用说明和安全提示

### 2. 登录确认页面 (`/passport/qr-confirm/index`)
- 处理二维码跳转确认
- 支持URL参数：`qrCodeKey` 或 `token`
- 用户确认界面

### 3. 功能测试页面 (`/passport/qr-test/index`)
- 演示各种集成方式
- 功能测试和调试

## 🛠️ 开发指南

### 1. 添加扫码按钮到现有页面

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

const MyPage = () => {
  return (
    <View>
      <QRLoginButton
        text="扫码登录"
        onSuccess={(result) => {
          // 处理登录成功
          console.log('用户登录成功:', result);
        }}
        onError={(error) => {
          // 处理登录失败
          console.error('登录失败:', error);
        }}
      />
    </View>
  );
};
```

### 2. 自定义扫码逻辑

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

const MyComponent = () => {
  const {
    startScan,
    isLoading,
    isSuccess,
    result,
    error
  } = useQRLogin();

  return (
    <Button
      loading={isLoading}
      onClick={startScan}
    >
      {isLoading ? '扫码中...' : '扫码登录'}
    </Button>
  );
};
```

## 🔒 安全注意事项

1. **用户登录验证**：使用前确保用户已在小程序中登录
2. **Token有效期**：二维码5分钟有效期，过期自动失效
3. **权限申请**：确保小程序已申请摄像头权限
4. **来源验证**：只扫描来自官方网站的登录二维码

## 🐛 常见问题

### Q: 提示"请先登录小程序"
A: 用户需要先在小程序中完成登录，获取用户ID和访问令牌。

### Q: 提示"无效的登录二维码"
A: 检查二维码格式是否正确，或者二维码是否已过期。

### Q: 扫码失败
A: 检查摄像头权限，确保二维码清晰可见。

### Q: 网络请求失败
A: 检查网络连接和API接口地址配置。

## 📚 相关文档

- [详细使用指南](docs/QR_LOGIN_USAGE.md)
- [API接口文档](src/api/qr-login/index.ts)
- [组件API文档](docs/QR_LOGIN_USAGE.md#组件api)

## 🎉 测试功能

访问测试页面验证功能：
```
/pages/qr-test/index
```

该页面包含所有集成方式的演示和测试功能。

## 📞 技术支持

如有问题，请检查：
1. 后端API服务是否正常运行
2. 小程序用户是否已登录
3. 网络连接是否正常
4. 二维码格式是否正确

---

**开发者**: 科技小王子  
**更新时间**: 2025-09-20