# 礼品卡二维码核销功能实现说明

## 功能概述

将礼品卡的"立即使用"功能改为生成二维码，供门店工作人员扫码核销，提升用户体验和核销效率。

## 核心功能

### 1. 用户端功能
- **生成核销二维码**：点击"立即使用"按钮生成包含核销信息的二维码
- **显示核销码**：同时显示6位数字核销码，支持手动输入
- **复制功能**：支持复制核销码和兑换码
- **刷新功能**：可重新生成新的核销码

### 2. 门店端功能
- **扫码核销**：使用摄像头扫描用户的二维码
- **手动输入**：支持手动输入核销码进行验证
- **信息验证**：显示礼品卡详细信息供确认
- **完成核销**：确认后完成核销操作

## 技术实现

### 1. 组件结构

#### GiftCardQRCode 组件
```typescript
interface GiftCardQRCodeProps {
  visible: boolean
  onClose: () => void
  giftCard: {
    id: number
    name?: string
    goodsName?: string
    code?: string
    faceValue?: string
    type?: number
    status?: number
    expireTime?: string
    contactInfo?: string
  }
}
```

**主要功能**：
- 生成核销二维码
- 显示礼品卡信息
- 提供复制和分享功能

#### StoreVerification 页面
**主要功能**：
- 扫码识别二维码
- 手动输入核销码
- 验证礼品卡信息
- 完成核销操作

### 2. 数据流程

#### 二维码数据结构
```json
{
  "type": "gift_card_verification",
  "giftId": 123,
  "giftCode": "SB2024001234567890",
  "verificationCode": "123456",
  "faceValue": "100",
  "timestamp": 1692123456789,
  "expireTime": "2024-12-31 23:59:59",
  "codeExpireTime": "2024-08-16 15:30:00"
}
```

#### 核销流程
1. **生成核销码**
   ```typescript
   POST /shop/shop-gift/generate-verification-code
   Body: { giftId: number }
   Response: { verificationCode: string, expireTime: string }
   ```

2. **验证核销码**
   ```typescript
   POST /shop/shop-gift/verify
   Body: { verificationCode?: string, giftCode?: string }
   Response: ShopGift
   ```

3. **完成核销**
   ```typescript
   POST /shop/shop-gift/complete-verification
   Body: { 
     giftId: number,
     verificationCode: string,
     storeId?: number,
     storeName?: string,
     operatorId?: number,
     operatorName?: string
   }
   ```

### 3. 安全机制

#### 核销码安全
- **时效性**：核销码有效期15分钟
- **一次性**：每次生成新的核销码
- **随机性**：6位随机数字，防止猜测

#### 验证机制
- **双重验证**：支持二维码和手动输入
- **信息确认**：显示完整礼品卡信息供确认
- **状态检查**：验证礼品卡状态和有效期

## 文件结构

### 新增文件
```
src/
├── components/
│   └── GiftCardQRCode.tsx          # 二维码核销弹窗组件
├── pages/
│   └── store/
│       └── verification.tsx        # 门店核销页面
├── user/gift/
│   ├── qrcode-demo.tsx            # 二维码功能演示页面
│   └── qrcode-verification-implementation.md
└── api/shop/shopGift/
    └── index.ts                    # 新增核销相关API
```

### 修改文件
```
src/
└── components/
    └── GiftCard.tsx                # 修改"立即使用"按钮功能
```

## 用户体验优化

### 1. 界面设计
- **清晰的二维码显示**：大尺寸二维码，易于扫描
- **信息完整展示**：显示礼品卡所有关键信息
- **操作便捷**：一键复制、刷新等快捷操作

### 2. 交互优化
- **即时反馈**：生成、验证过程有明确的加载状态
- **错误处理**：友好的错误提示和重试机制
- **状态管理**：清晰的状态流转和视觉反馈

### 3. 兼容性考虑
- **多种核销方式**：支持扫码和手动输入
- **设备适配**：适配不同尺寸的移动设备
- **网络容错**：网络异常时的降级处理

## 业务流程

### 用户使用流程
1. 用户在礼品卡列表点击"立即使用"
2. 系统生成核销二维码和核销码
3. 用户向门店工作人员出示二维码
4. 工作人员扫码或输入核销码
5. 系统验证信息并显示礼品卡详情
6. 工作人员确认后完成核销
7. 礼品卡状态更新为已使用

### 门店操作流程
1. 打开门店核销页面
2. 扫描用户二维码或手动输入核销码
3. 系统验证并显示礼品卡信息
4. 确认信息无误后点击"确认核销"
5. 完成核销，用户礼品卡状态更新

## 测试验证

### 1. 功能测试
- **二维码生成**：验证二维码正确生成和显示
- **核销码生成**：验证6位数字核销码的随机性
- **扫码识别**：验证二维码能被正确解析
- **手动输入**：验证手动输入核销码的准确性
- **核销完成**：验证核销后状态正确更新

### 2. 安全测试
- **时效性测试**：验证核销码过期机制
- **重复使用测试**：验证核销码不能重复使用
- **状态验证**：验证只有未使用的礼品卡能生成核销码

### 3. 用户体验测试
- **界面响应**：验证各种操作的响应速度
- **错误处理**：验证各种异常情况的处理
- **设备兼容**：验证在不同设备上的显示效果

## 部署注意事项

### 1. 后端API
- 确保核销相关API已部署
- 配置核销码有效期（建议15分钟）
- 设置适当的并发限制

### 2. 权限配置
- 门店核销页面需要相应权限
- 核销操作需要记录操作人信息

### 3. 监控告警
- 监控核销成功率
- 监控异常核销请求
- 设置核销量异常告警

## 后续优化建议

1. **批量核销**：支持一次核销多张礼品卡
2. **核销统计**：提供核销数据统计和报表
3. **离线核销**：支持网络异常时的离线核销
4. **核销记录**：详细的核销历史记录查询
5. **多门店支持**：支持多门店的核销管理