feat(auth): 实现二维码登录功能

- 新增二维码登录相关接口和页面 - 实现二维码生成、状态检查、登录确认等逻辑 - 添加微信小程序登录支持- 优化用户信息展示和处理
2025-09-05 22:49:41 +08:00
parent 0dfe3934a4
commit 408ff13590
18 changed files with 1558 additions and 10 deletions
--- a/docs/统一扫码功能说明.md
+++ b/docs/统一扫码功能说明.md
@@ -0,0 +1,182 @@
+# 统一扫码功能说明
+
+## 📋 功能概述
+
+本项目实现了统一扫码入口，支持多种类型的二维码识别和处理：
+
+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` - 支持从统一扫码传递参数
+
+## 🎯 使用方法
+
+### 在组件中使用统一扫码
+
+```typescript
+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>
+  );
+}
+```
+
+### 扫码结果类型
+
+```typescript
+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 参数
+```typescript
+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. **离线支持**：部分功能支持离线处理