template-10550/docs/UNIFIED_QR_SCAN_GUIDE.md

统一扫码功能使用指南

🎯 功能概述

统一扫码功能将原有的扫码登录和扫码核销合并为一个入口，通过智能识别二维码内容自动执行相应操作。

📋 功能特性

✨ 智能识别

• 自动识别登录二维码和核销二维码
• 根据二维码内容自动执行相应操作
• 支持多种二维码格式（JSON加密、纯文本等）

🔄 统一体验

• 一个按钮解决两种扫码需求
• 统一的UI界面和交互逻辑
• 一致的错误处理和状态提示

📱 多入口支持

• 用户卡片中的统一扫码按钮
• 管理员面板中的统一扫码功能
• 独立的统一扫码页面

🛠️ 技术实现

核心文件

src/
├── hooks/
│   └── useUnifiedQRScan.ts        # 统一扫码Hook
├── components/
│   └── UnifiedQRButton.tsx        # 统一扫码按钮组件
└── pages/
    └── unified-qr/
        ├── index.tsx              # 统一扫码页面
        └── index.config.ts        # 页面配置

Hook：useUnifiedQRScan

import { useUnifiedQRScan, ScanType } from '@/hooks/useUnifiedQRScan';

const {
  startScan,     // 开始扫码
  isLoading,     // 加载状态
  canScan,       // 是否可以扫码
  state,         // 当前状态
  result,        // 扫码结果
  scanType,      // 识别的扫码类型
  reset          // 重置状态
} = useUnifiedQRScan();

组件：UnifiedQRButton

<UnifiedQRButton
  text="扫码"
  size="small"
  onSuccess={(result) => {
    console.log('扫码成功:', result);
    // result.type: 'login' | 'verification'
    // result.data: 具体数据
    // result.message: 成功消息
  }}
  onError={(error) => {
    console.error('扫码失败:', error);
  }}
/>

🎮 使用方式

1. 直接使用统一按钮

import UnifiedQRButton from '@/components/UnifiedQRButton';

// 在需要的地方使用
<UnifiedQRButton
  text="智能扫码"
  onSuccess={(result) => {
    if (result.type === 'login') {
      // 处理登录成功
    } else if (result.type === 'verification') {
      // 处理核销成功
    }
  }}
/>

2. 跳转到统一扫码页面

// 跳转到统一扫码页面
Taro.navigateTo({
  url: '/passport/unified-qr/index'
});

3. 在管理员面板中使用

管理员面板已更新，原来的"门店核销"和"扫码登录"合并为"统一扫码"。

🔍 二维码识别逻辑

登录二维码

• 格式: 包含登录token的URL或纯文本
• 处理: 自动解析token并确认登录
• 示例: https://example.com/login?token=xxx

核销二维码

• JSON格式: {"businessType":"gift","token":"xxx","data":"encrypted_data"}
• 纯文本格式: 6位数字核销码
• 处理: 解密数据（如需要）-> 验证核销码 -> 执行核销

识别优先级

1. 首先检查是否为JSON格式的核销二维码
2. 然后检查是否为登录二维码
3. 最后检查是否为纯数字核销码
4. 如果都不匹配，提示"不支持的二维码类型"

📊 用户体验优化

智能提示

• 扫码过程中显示当前状态
• 根据识别结果给出相应提示
• 核销成功后询问是否继续扫码

历史记录

• 保留最近5次扫码记录
• 显示扫码类型、时间和结果
• 方便用户查看操作历史

错误处理

• 统一的错误提示机制
• 具体的错误原因说明
• 便捷的重试和重置功能

🔄 迁移指南

从原有功能迁移

替换扫码登录按钮

// 原来
<QRLoginButton />

// 现在
<UnifiedQRButton text="扫码登录" />

替换核销按钮

// 原来
<Button onClick={() => navTo('/user/store/verification')}>
  扫码核销
</Button>

// 现在
<UnifiedQRButton text="扫码核销" />

管理员面板更新

管理员面板自动合并了原有的两个扫码功能，无需额外操作。

🚀 优势总结

用户体验

• ✅ 简化操作: 一个按钮处理所有扫码需求
• ✅ 智能识别: 无需用户手动选择扫码类型
• ✅ 统一界面: 一致的交互体验

开发维护

• ✅ 代码复用: 统一的扫码逻辑和错误处理
• ✅ 易于扩展: 新增扫码类型只需修改识别逻辑
• ✅ 降低复杂度: 减少重复代码和功能入口

功能完整性

• ✅ 保留所有原功能: 登录和核销功能完全保留
• ✅ 增强用户体验: 添加历史记录和智能提示
• ✅ 向后兼容: 原有的单独页面仍然可用

🔧 配置说明

页面路由配置

需要在 app.config.ts 中添加新页面路由：

export default {
  pages: [
    // ... 其他页面
    'passport/unified-qr/index'
  ]
}

权限要求

• 扫码权限: 所有用户都可以扫码
• 登录功能: 需要用户已登录小程序
• 核销功能: 需要管理员权限

🎯 未来规划

扩展可能性

• 支持更多类型的二维码（商品码、活动码等）
• 增加扫码统计和分析功能
• 支持批量扫码操作
• 增加扫码记录的云端同步

性能优化

• 扫码响应速度优化
• 二维码识别准确率提升
• 网络请求优化和缓存机制