billiard-app/QR_CODE_DESIGN.md

二维码设计方案

📋 业务分析

扫码场景分析

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 格式 ✅ 推荐

{
  "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. 二维码生成接口

// 后端接口设计
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. 二维码类型定义

enum QRCodeType {
  TABLE_START = 'table_start',    // 开台
  TABLE_CLOSE = 'table_close',    // 关台  
  CABINET = 'cabinet',            // 存杆柜
  COUPON = 'coupon'              // 团购券
}

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

开台二维码

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

关台二维码

{
  "type": "table_close",
  "grpSn": "TB001",           // 设备编码（必需）
  "tableId": "table_123",     // 球桌ID（必需）
  "orderId": "order_789"      // 订单ID（可选）
}

存杆柜二维码

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

团购券二维码

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

🔄 跳转逻辑流程

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 中已添加：

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. 重点关注二维码的数据结构设计，确保包含必要的业务参数

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