# 二维码设计方案

## 📋 **业务分析**

### **扫码场景分析**
1. **开台扫码** - 扫描球桌二维码进行开台
2. **关台扫码** - 扫描球桌二维码进行关台  
3. **存杆柜扫码** - 扫描存杆柜二维码进行存取
4. **团购券扫码** - 扫描团购券二维码使用优惠

### **跳转页面映射**
```
pageScan/startTable/index     - 开台选择页面
pageScan/selfStart/index      - 自助开台页面  
pageScan/timedStart/index     - 定时开台页面
pageScan/couponStart/index    - 团购券开台页面
pageScan/closeTable/index     - 关台页面
pageScan/renewFee/index       - 续费页面
pageScan/turnOffRestart/index - 关灯重开页面
pageScan/myCoupons/index      - 我的卡券页面
pageScan/couponUse/index      - 卡券使用页面
```

## 🎯 **推荐方案**

### **1. 统一处理页面** ✅ 推荐
**使用 `pages/qrHandler/index` 作为统一的二维码处理入口**

**优势：**
- ✅ 统一的跳转逻辑，便于维护
- ✅ 支持微信扫码和小程序内扫码
- ✅ 错误处理集中化
- ✅ 便于添加埋点和日志
- ✅ 支持复杂的业务逻辑判断

**使用场景：**
1. **微信扫码进入小程序**：`pages/qrHandler/index?q=xxx`
2. **小程序内扫码**：`pages/qrHandler/index?qrContent=xxx`
3. **小程序码**：`pages/qrHandler/index?scene=xxx`

### **2. 二维码内容格式设计**

#### **方案A：JSON 格式** ✅ 推荐
```json
{
  "type": "table_start",
  "grpSn": "TB001",
  "tableId": "table_123",
  "storeId": "store_456"
}
```

#### **方案B：URL 格式**
```
https://yourdomain.com/qr?type=table_start&grpSn=TB001&tableId=table_123&storeId=store_456
```

#### **方案C：简单格式**
```
table_start:TB001:table_123:store_456
```

## 🛠️ **后端实现建议**

### **1. 二维码生成接口**
```typescript
// 后端接口设计
POST /api/v2/qrcode/generate
{
  "type": "table_start",    // 二维码类型
  "grpSn": "TB001",        // 设备编码
  "tableId": "table_123",   // 球桌ID
  "storeId": "store_456"    // 门店ID
}

// 返回
{
  "success": true,
  "data": {
    "qrContent": "{\"type\":\"table_start\",\"grpSn\":\"TB001\",\"tableId\":\"table_123\",\"storeId\":\"store_456\"}",
    "qrCodeUrl": "https://api.qrserver.com/v1/create-qr-code/?data=xxx"
  }
}
```

### **2. 二维码类型定义**
```typescript
enum QRCodeType {
  TABLE_START = 'table_start',    // 开台
  TABLE_CLOSE = 'table_close',    // 关台  
  CABINET = 'cabinet',            // 存杆柜
  COUPON = 'coupon'              // 团购券
}
```

### **3. 不同类型二维码的数据结构**

#### **开台二维码**
```json
{
  "type": "table_start",
  "grpSn": "TB001",           // 设备编码（必需）
  "tableId": "table_123",     // 球桌ID（必需）
  "storeId": "store_456",     // 门店ID（必需）
  "tableName": "1号台",       // 球桌名称（可选）
  "storeInfo": {              // 门店信息（可选）
    "name": "黑八大师联盟球厅",
    "address": "xxx路xxx号"
  }
}
```

#### **关台二维码**
```json
{
  "type": "table_close",
  "grpSn": "TB001",           // 设备编码（必需）
  "tableId": "table_123",     // 球桌ID（必需）
  "orderId": "order_789"      // 订单ID（可选）
}
```

#### **存杆柜二维码**
```json
{
  "type": "cabinet",
  "cabinetId": "cabinet_001", // 存杆柜ID（必需）
  "storeId": "store_456",     // 门店ID（必需）
  "cabinetNo": "A01"          // 存杆柜编号（可选）
}
```

#### **团购券二维码**
```json
{
  "type": "coupon",
  "couponCode": "MT123456",   // 团购券码（必需）
  "platform": "meituan",     // 平台：meituan/douyin/dianping（可选）
  "value": 50.00             // 券面值（可选）
}
```

## 🔄 **跳转逻辑流程**

```mermaid
graph TD
    A[用户扫码] --> B[qrHandler页面]
    B --> C[解析二维码内容]
    C --> D{判断二维码类型}
    
    D -->|table_start| E[跳转开台选择页面]
    D -->|table_close| F[跳转关台页面]  
    D -->|cabinet| G[跳转存杆柜页面]
    D -->|coupon| H[跳转团购券使用页面]
    D -->|unknown| I[显示错误提示]
    
    E --> J[startTable/index]
    F --> K[closeTable/index]
    G --> L[poleStorage/index]
    H --> M[couponUse/index]
```

## 📱 **小程序配置**

### **1. 页面路径配置**
在 `app.config.ts` 中已添加：
```typescript
pages: [
  // ...
  'pages/qrHandler/index', // 统一二维码处理页面
]
```

### **2. 微信扫码跳转配置**
需要在微信公众平台配置小程序的扫码跳转规则：
- 扫码跳转页面：`pages/qrHandler/index`
- 参数传递：通过 `q` 参数传递二维码内容

## ⚠️ **注意事项**

### **1. 安全考虑**
- 二维码内容建议加密或签名
- 添加时效性验证
- 防止二维码被恶意复制使用

### **2. 用户体验**
- 添加加载状态提示
- 错误情况下提供明确的引导
- 支持重新扫码功能

### **3. 兼容性**
- 支持多种二维码格式解析
- 向后兼容旧版本二维码
- 处理异常情况的降级方案

## 🚀 **实施步骤**

1. ✅ **前端已完成**：
   - 创建二维码处理工具 `qrCodeHandler.ts`
   - 创建统一处理页面 `qrHandler/index`
   - 更新扫码页面集成新逻辑

2. 🔄 **后端需要实现**：
   - 二维码生成接口
   - 不同类型二维码的数据结构
   - 二维码验证和安全机制

3. 🔄 **测试验证**：
   - 各种类型二维码的跳转测试
   - 异常情况的处理测试
   - 微信扫码进入的测试

## 💡 **总结建议**

**给后端的建议：**
1. **使用统一的 `pages/qrHandler/index` 页面**作为所有二维码的处理入口
2. **二维码内容采用 JSON 格式**，便于扩展和解析
3. **不需要为每种业务单独创建处理页面**，统一处理更好维护
4. **重点关注二维码的数据结构设计**，确保包含必要的业务参数

这样的设计既保证了功能的完整性，又具有良好的可维护性和扩展性。