forked from gxwebsoft/mp-10550
feat(admin): 实现管理员模式切换和扫码登录功能
- 新增管理员模式切换方案，统一管理所有管理员功能 - 实现扫码登录功能，支持用户通过小程序扫描网页端二维码快速登录 - 添加管理员面板组件，集中展示所有管理员功能 - 开发扫码登录按钮和扫描器组件，方便集成到不同页面 - 优化用户界面设计，提高管理员用户的使用体验
This commit is contained in:
214
docs/QR_LOGIN_INTEGRATION.md
Normal file
214
docs/QR_LOGIN_INTEGRATION.md
Normal file
@@ -0,0 +1,214 @@
|
||||
# 微信小程序扫码登录集成文档
|
||||
|
||||
## 概述
|
||||
|
||||
本文档介绍如何在微信小程序中集成扫码登录功能，支持用户通过小程序扫描网页端二维码快速登录。
|
||||
|
||||
## 功能特性
|
||||
|
||||
- ✅ **多平台支持** - 支持网页端、移动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/pages/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: '/pages/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. 考虑网络异常和超时情况
|
||||
Reference in New Issue
Block a user