template-10550/src/user/gift/qrcode-verification-implementation.md

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

功能概述

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

核心功能

1. 用户端功能

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

2. 门店端功能

• 扫码核销：使用摄像头扫描用户的二维码
• 手动输入：支持手动输入核销码进行验证
• 信息验证：显示礼品卡详细信息供确认
• 完成核销：确认后完成核销操作

技术实现

1. 组件结构

GiftCardQRCode 组件

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. 数据流程

二维码数据结构

{
  "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. 生成核销码

   POST /shop/shop-gift/generate-verification-code
   Body: { giftId: number }
   Response: { verificationCode: string, expireTime: string }
   

2. 验证核销码

   POST /shop/shop-gift/verify
   Body: { verificationCode?: string, giftCode?: string }
   Response: ShopGift
   

3. 完成核销

   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. 多门店支持：支持多门店的核销管理