forked from gxwebsoft/mp-10550
feat(qr-login): 实现扫码登录功能模块
This commit is contained in:
209
README_QR_LOGIN.md
Normal file
209
README_QR_LOGIN.md
Normal file
@@ -0,0 +1,209 @@
|
||||
# 微信小程序扫码登录功能实现
|
||||
|
||||
## 项目概述
|
||||
|
||||
本项目已完整实现微信小程序扫码登录功能，支持用户通过小程序扫描网页端二维码快速登录。
|
||||
|
||||
## 🎯 功能特性
|
||||
|
||||
- ✅ **完整的后端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: '/pages/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. 扫码登录页面 (`/pages/qr-login/index`)
|
||||
- 完整的扫码登录功能
|
||||
- 用户信息显示
|
||||
- 登录历史记录
|
||||
- 使用说明和安全提示
|
||||
|
||||
### 2. 登录确认页面 (`/pages/qr-confirm/index`)
|
||||
- 处理二维码跳转确认
|
||||
- 支持URL参数：`qrCodeKey` 或 `token`
|
||||
- 用户确认界面
|
||||
|
||||
### 3. 功能测试页面 (`/pages/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
|
||||
Reference in New Issue
Block a user