template-10560/docs/统一扫码功能说明.md

统一扫码功能说明

📋 功能概述

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

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 - 支持从统一扫码传递参数

🎯 使用方法

在组件中使用统一扫码

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>
  );
}

扫码结果类型

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 参数

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