# 统一扫码功能说明

## 📋 功能概述

本项目实现了统一扫码入口，支持多种类型的二维码识别和处理：

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. **离线支持**：部分功能支持离线处理