# 二维码业务类型使用指南

## 概述

现在二维码系统支持业务类型（businessType）参数，允许前端在生成二维码时指定业务类型，解密后可以根据不同的业务类型进行相应的处理。

## 支持的业务类型示例

```javascript
// 常见的业务类型
const BUSINESS_TYPES = {
    ORDER: 'order',           // 订单二维码
    USER: 'user',             // 用户信息二维码
    COUPON: 'coupon',         // 优惠券二维码
    GIFT: 'gitf',             // 礼品卡二维码
    TICKET: 'ticket',         // 门票二维码
    PAYMENT: 'payment',       // 支付二维码
    CHECKIN: 'checkin',       // 签到二维码
    PRODUCT: 'product',       // 商品二维码
    MEMBER: 'member',         // 会员卡二维码
    PARKING: 'parking',       // 停车二维码
    ACCESS: 'access'          // 门禁二维码
};
```

## API 接口使用

### 1. 生成带业务类型的加密二维码

```http
POST /api/qr-code/create-encrypted-qr-code
```

**参数：**
```javascript
{
    data: "order_id:12345,amount:88.50",
    width: 300,
    height: 300,
    expireMinutes: 60,
    businessType: "order"  // 新增的业务类型参数
}
```

**响应：**
```json
{
    "code": 200,
    "message": "生成加密二维码成功",
    "data": {
        "qrCodeBase64": "iVBORw0KGgoAAAANSUhEUgAA...",
        "token": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
        "originalData": "order_id:12345,amount:88.50",
        "expireMinutes": "60",
        "businessType": "order"
    }
}
```

### 2. 解密二维码（返回完整结果）

```http
POST /api/qr-code/verify-and-decrypt-qr-with-type
```

**参数：**
```javascript
{
    qrContent: '{"token":"...","data":"...","type":"encrypted","businessType":"order"}'
}
```

**响应：**
```json
{
    "code": 200,
    "message": "验证和解密成功",
    "data": {
        "originalData": "order_id:12345,amount:88.50",
        "businessType": "order",
        "qrType": "encrypted",
        "qrId": null,
        "expireTime": null,
        "expired": false
    }
}
```

### 3. 生成业务模式二维码

```http
POST /api/qr-code/create-business-encrypted-qr-code
```

**参数：**
```javascript
{
    data: "coupon_id:C001,discount:20%",
    businessKey: "store_001_secret",
    width: 250,
    height: 250,
    expireMinutes: 120,
    businessType: "coupon"
}
```

## 前端使用示例

### 场景1：餐厅点餐系统

```javascript
// 1. 生成订单二维码
async function generateOrderQrCode(orderData) {
    const response = await fetch('/api/qr-code/create-encrypted-qr-code', {
        method: 'POST',
        headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
        body: new URLSearchParams({
            data: JSON.stringify(orderData),
            businessType: 'order',
            expireMinutes: 30
        })
    });
    
    const result = await response.json();
    return result.data;
}

// 2. 扫码处理订单
async function handleQrCodeScan(qrContent) {
    const response = await fetch('/api/qr-code/verify-and-decrypt-qr-with-type', {
        method: 'POST',
        headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
        body: new URLSearchParams({ qrContent })
    });
    
    const result = await response.json();
    if (result.code === 200) {
        const { originalData, businessType } = result.data;
        
        // 根据业务类型处理不同逻辑
        switch (businessType) {
            case 'order':
                handleOrderQrCode(originalData);
                break;
            case 'coupon':
                handleCouponQrCode(originalData);
                break;
            case 'user':
                handleUserQrCode(originalData);
                break;
            default:
                console.log('未知的业务类型:', businessType);
        }
    }
}

// 3. 处理订单二维码
function handleOrderQrCode(orderData) {
    const order = JSON.parse(orderData);
    console.log('处理订单:', order);
    
    // 跳转到订单详情页
    window.location.href = `/order/detail?id=${order.orderId}`;
}

// 4. 处理优惠券二维码
function handleCouponQrCode(couponData) {
    const coupon = JSON.parse(couponData);
    console.log('处理优惠券:', coupon);
    
    // 显示优惠券使用界面
    showCouponDialog(coupon);
}
```

### 场景2：会员系统

```javascript
// 生成会员卡二维码
async function generateMemberQrCode(memberId) {
    const memberData = {
        memberId: memberId,
        timestamp: Date.now()
    };
    
    const qrResult = await generateQrCode({
        data: JSON.stringify(memberData),
        businessType: 'member',
        expireMinutes: 1440 // 24小时
    });
    
    return qrResult;
}

// 扫码验证会员
async function verifyMemberQrCode(qrContent) {
    const result = await verifyQrCode(qrContent);
    
    if (result.businessType === 'member') {
        const memberData = JSON.parse(result.originalData);
        
        // 验证会员身份
        const member = await getMemberInfo(memberData.memberId);
        if (member) {
            showMemberInfo(member);
        } else {
            showError('会员不存在');
        }
    }
}
```

### 场景3：门店核销系统

```javascript
// 门店核销优惠券
async function verifyStoreCoupon(qrContent, storeKey) {
    const response = await fetch('/api/qr-code/verify-business-qr', {
        method: 'POST',
        headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
        body: new URLSearchParams({
            qrContent: qrContent,
            businessKey: storeKey
        })
    });
    
    const result = await response.json();
    if (result.code === 200) {
        // 解析二维码内容获取业务类型
        const qrData = JSON.parse(qrContent);
        const businessType = qrData.businessType;
        
        switch (businessType) {
            case 'coupon':
                handleCouponVerification(result.data);
                break;
            case 'ticket':
                handleTicketVerification(result.data);
                break;
            default:
                console.log('门店不支持此类型的二维码:', businessType);
        }
    }
}
```

## 业务类型的好处

### 1. **前端路由分发**
```javascript
function routeByBusinessType(businessType, data) {
    const routes = {
        'order': '/order/scan',
        'coupon': '/coupon/verify',
        'user': '/user/profile',
        'ticket': '/ticket/check',
        'payment': '/payment/process'
    };
    
    const route = routes[businessType];
    if (route) {
        window.location.href = `${route}?data=${encodeURIComponent(data)}`;
    }
}
```

### 2. **权限控制**
```javascript
function checkPermission(businessType, userRole) {
    const permissions = {
        'order': ['waiter', 'manager'],
        'coupon': ['cashier', 'manager'],
        'ticket': ['security', 'manager'],
        'payment': ['cashier', 'manager']
    };
    
    return permissions[businessType]?.includes(userRole);
}
```

### 3. **统计分析**
```javascript
function trackQrCodeUsage(businessType, action) {
    analytics.track('qr_code_scan', {
        business_type: businessType,
        action: action,
        timestamp: Date.now()
    });
}
```

## 注意事项

1. **业务类型验证**：前端应该验证业务类型是否符合预期
2. **权限检查**：根据业务类型检查用户是否有相应权限
3. **错误处理**：优雅处理未知的业务类型
4. **安全性**：业务类型不应包含敏感信息
5. **向后兼容**：支持没有业务类型的旧二维码

## 最佳实践

1. **统一业务类型常量**：在前后端定义统一的业务类型常量
2. **类型验证**：在解密后验证业务类型是否符合当前场景
3. **日志记录**：记录不同业务类型的使用情况
4. **监控告警**：监控异常的业务类型使用
5. **文档维护**：及时更新业务类型的文档说明
