template-10584/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

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

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

### 组件：UnifiedQRButton

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

## 🎮 使用方式

### 1. 直接使用统一按钮
```jsx
import UnifiedQRButton from '@/components/UnifiedQRButton';

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

### 2. 跳转到统一扫码页面
```jsx
// 跳转到统一扫码页面
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次扫码记录
- 显示扫码类型、时间和结果
- 方便用户查看操作历史

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

## 🔄 迁移指南

### 从原有功能迁移

#### 替换扫码登录按钮
```jsx
// 原来
<QRLoginButton />

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

#### 替换核销按钮
```jsx
// 原来
<Button onClick={() => navTo('/user/store/verification')}>
  扫码核销
</Button>

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

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

## 🚀 优势总结

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

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

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

## 🔧 配置说明

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

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

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

## 🎯 未来规划

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

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