183 lines
4.8 KiB
Markdown
183 lines
4.8 KiB
Markdown
# 统一扫码功能说明
|
||
|
||
## 📋 功能概述
|
||
|
||
本项目实现了统一扫码入口，支持多种类型的二维码识别和处理：
|
||
|
||
1. **二维码登录** - 扫码确认后台管理系统登录
|
||
2. **礼品卡核销** - 管理员扫码核销礼品卡
|
||
3. **礼品卡兑换** - 用户扫码兑换礼品卡
|
||
4. **车辆查询** - 扫码查询车辆信息
|
||
5. **未知类型** - 提供选择处理方式
|
||
|
||
## 🔧 技术实现
|
||
|
||
### 核心组件
|
||
|
||
#### 1. API接口层 (`src/api/qrLogin/`)
|
||
- `model/index.ts` - 类型定义
|
||
- `index.ts` - API接口和扫码结果解析逻辑
|
||
|
||
#### 2. 统一扫码组件 (`src/components/UniversalScanner.tsx`)
|
||
- `useUniversalScanner` Hook - 提供扫码功能
|
||
- 智能识别不同类型的二维码
|
||
- 权限控制和错误处理
|
||
|
||
#### 3. 用户界面集成
|
||
- `UserCard.tsx` - 移除管理员权限限制，所有登录用户可见扫码按钮
|
||
- `verification.tsx` - 支持从统一扫码传递参数
|
||
|
||
## 🎯 使用方法
|
||
|
||
### 在组件中使用统一扫码
|
||
|
||
```typescript
|
||
import { useUniversalScanner } from '@/components/UniversalScanner';
|
||
|
||
function MyComponent() {
|
||
const { startScan } = useUniversalScanner({
|
||
onScanSuccess: (result) => {
|
||
console.log('扫码成功:', result);
|
||
},
|
||
onScanError: (error) => {
|
||
console.error('扫码失败:', error);
|
||
}
|
||
});
|
||
|
||
return (
|
||
<Button onClick={startScan}>
|
||
扫码
|
||
</Button>
|
||
);
|
||
}
|
||
```
|
||
|
||
### 扫码结果类型
|
||
|
||
```typescript
|
||
export type ScanResultType =
|
||
| 'qr-login' // 二维码登录
|
||
| 'gift-verification' // 礼品卡核销
|
||
| 'gift-redeem' // 礼品卡兑换
|
||
| 'vehicle-query' // 车辆查询
|
||
| 'unknown'; // 未知类型
|
||
```
|
||
|
||
## 🔍 二维码格式识别规则
|
||
|
||
### 1. 二维码登录
|
||
- 格式：`qr-login:token` 或纯token（32位以上字符串）
|
||
- 示例：`qr-login:abc123def456...` 或 `abc123def456ghi789...`
|
||
|
||
### 2. 礼品卡核销
|
||
- 格式：JSON格式，包含 `businessType: 'gift'`
|
||
- 示例：`{"businessType":"gift","token":"xxx","data":"yyy"}`
|
||
|
||
### 3. 礼品卡兑换
|
||
- 格式：6位字母数字组合
|
||
- 示例：`ABC123`、`XYZ789`
|
||
|
||
### 4. 车辆查询
|
||
- 格式：以 `vehicle-` 或 `car-` 开头
|
||
- 示例：`vehicle-12345`、`car-abc123`
|
||
|
||
### 5. URL格式
|
||
- 支持包含特定参数的URL
|
||
- 二维码登录：包含 `qr-login-token` 参数
|
||
- 礼品卡：包含 `gift-code` 参数
|
||
|
||
## 🛡️ 权限控制
|
||
|
||
### 用户权限
|
||
- **所有已登录用户**：可以看到扫码按钮
|
||
- **二维码登录**：需要登录状态
|
||
- **礼品卡兑换**：无需特殊权限
|
||
- **车辆查询**：无需特殊权限
|
||
|
||
### 管理员权限
|
||
- **礼品卡核销**：仅管理员可用
|
||
|
||
## 🔄 处理流程
|
||
|
||
### 二维码登录流程
|
||
1. 扫码获取token
|
||
2. 调用 `scanQrCode(token)` 更新状态为已扫码
|
||
3. 调用 `wechatMiniProgramConfirm()` 确认登录
|
||
4. 显示成功提示
|
||
|
||
### 礼品卡核销流程
|
||
1. 检查管理员权限
|
||
2. 跳转到核销页面并传递扫码数据
|
||
3. 在核销页面处理解密和验证
|
||
|
||
### 礼品卡兑换流程
|
||
1. 直接跳转到兑换页面
|
||
2. 传递兑换码参数
|
||
|
||
## 🚨 错误处理
|
||
|
||
### 常见错误类型
|
||
- **权限不足**：非管理员尝试核销
|
||
- **未登录**：需要登录的功能
|
||
- **二维码过期**：登录token过期
|
||
- **无效二维码**：格式不正确
|
||
- **网络错误**：API调用失败
|
||
|
||
### 错误提示
|
||
- 自动显示Toast提示
|
||
- 根据错误类型显示不同消息
|
||
- 支持自定义错误处理回调
|
||
|
||
## 📱 用户体验
|
||
|
||
### 成功提示
|
||
- **二维码登录**：显示确认弹窗，提示在电脑端查看
|
||
- **其他功能**：显示成功Toast并跳转相应页面
|
||
|
||
### 未知类型处理
|
||
- 显示操作选择弹窗
|
||
- 提供复制、作为礼品卡码、作为车辆码等选项
|
||
|
||
## 🔧 配置选项
|
||
|
||
### useUniversalScanner 参数
|
||
```typescript
|
||
interface UniversalScannerProps {
|
||
/** 扫码成功回调 */
|
||
onScanSuccess?: (result: ScanResultParsed) => void;
|
||
/** 扫码失败回调 */
|
||
onScanError?: (error: string) => void;
|
||
/** 是否显示处理结果提示 */
|
||
showToast?: boolean;
|
||
}
|
||
```
|
||
|
||
## 🧪 测试建议
|
||
|
||
### 测试场景
|
||
1. **不同用户权限**：普通用户、管理员
|
||
2. **不同二维码类型**：登录、核销、兑换、车辆查询
|
||
3. **错误情况**：过期、无效、网络错误
|
||
4. **边界情况**：未登录、权限不足
|
||
|
||
### 测试数据
|
||
- 有效的登录token
|
||
- 有效的礼品卡核销JSON
|
||
- 有效的兑换码（6位）
|
||
- 有效的车辆查询码
|
||
- 无效/过期的各种码
|
||
|
||
## 📝 注意事项
|
||
|
||
1. **安全性**：登录token应该有过期时间
|
||
2. **性能**：扫码解析逻辑应该高效
|
||
3. **用户体验**：错误提示应该清晰明确
|
||
4. **扩展性**：新增扫码类型时只需修改解析逻辑
|
||
|
||
## 🔄 后续优化
|
||
|
||
1. **缓存机制**：缓存扫码结果避免重复处理
|
||
2. **统计功能**：记录扫码使用情况
|
||
3. **批量处理**：支持连续扫码
|
||
4. **离线支持**：部分功能支持离线处理
|