# QR码API使用说明

## 概述

QR码API已经升级为接收JSON格式的请求数据，提供更好的类型安全和扩展性。

## API接口说明

### 1. 生成加密二维码

**接口地址：** `POST /api/qr-code/create-encrypted-qr-code`

**请求格式：** JSON

**请求示例：**
```json
{
  "data": "用户ID:12345",
  "width": 200,
  "height": 200,
  "expireMinutes": 30,
  "businessType": "LOGIN"
}
```

**参数说明：**
- `data` (必填): 要加密的数据
- `width` (可选): 二维码宽度，默认200，范围50-1000
- `height` (可选): 二维码高度，默认200，范围50-1000
- `expireMinutes` (可选): 过期时间（分钟），默认30，范围1-1440
- `businessType` (可选): 业务类型

### 2. 解密二维码数据

**接口地址：** `POST /api/qr-code/decrypt-qr-data`

**请求示例：**
```json
{
  "token": "abc123def456",
  "encryptedData": "encrypted_data_string"
}
```

### 3. 验证并解密二维码内容

**接口地址：** `POST /api/qr-code/verify-and-decrypt-qr`

**请求示例：**
```json
{
  "qrContent": "qr_content_string"
}
```

### 4. 验证并解密二维码内容（返回完整结果）

**接口地址：** `POST /api/qr-code/verify-and-decrypt-qr-with-type`

**请求示例：**
```json
{
  "qrContent": "qr_content_string"
}
```

### 5. 生成业务加密二维码

**接口地址：** `POST /api/qr-code/create-business-encrypted-qr-code`

**请求示例：**
```json
{
  "data": "订单ID:ORDER123",
  "businessKey": "store_key_123",
  "width": 200,
  "height": 200,
  "expireMinutes": 30,
  "businessType": "ORDER"
}
```

### 6. 门店核销二维码

**接口地址：** `POST /api/qr-code/verify-business-qr`

**请求示例：**
```json
{
  "qrContent": "qr_content_string",
  "businessKey": "store_key_123"
}
```

### 7. 使token失效

**接口地址：** `POST /api/qr-code/invalidate-token`

**请求示例：**
```json
{
  "token": "abc123def456"
}
```

## GET接口（保持不变）

以下GET接口保持原有的@RequestParam方式：

### 生成普通二维码
`GET /api/qr-code/create-qr-code?data=要编码的数据&size=200x200`

### 生成加密二维码图片流
`GET /api/qr-code/create-encrypted-qr-image?data=要加密的数据&size=200x200&expireMinutes=30&businessType=LOGIN`

**参数说明：**
- `data` (必填): 要加密的数据
- `size` (可选): 二维码尺寸，格式：宽x高，默认200x200
- `expireMinutes` (可选): 过期时间（分钟），默认30
- `businessType` (可选): 业务类型，如LOGIN、ORDER等

### 检查token是否有效
`GET /api/qr-code/check-token?token=abc123def456`

## 错误处理

API现在包含完整的参数验证，会返回具体的错误信息：

**验证失败示例：**
```json
{
  "code": 500,
  "message": "数据不能为空",
  "data": null
}
```

**常见验证错误：**
- "数据不能为空"
- "宽度不能小于50像素"
- "宽度不能大于1000像素"
- "过期时间不能小于1分钟"
- "过期时间不能大于1440分钟"
- "token不能为空"
- "业务密钥不能为空"

## 前端调用示例

### JavaScript/Axios
```javascript
// 生成加密二维码
const response = await axios.post('/api/qr-code/create-encrypted-qr-code', {
  data: '用户ID:12345',
  width: 200,
  height: 200,
  expireMinutes: 30,
  businessType: 'LOGIN'
});

console.log(response.data);
```

### jQuery
```javascript
$.ajax({
  url: '/api/qr-code/create-encrypted-qr-code',
  type: 'POST',
  contentType: 'application/json',
  data: JSON.stringify({
    data: '用户ID:12345',
    width: 200,
    height: 200,
    expireMinutes: 30,
    businessType: 'LOGIN'
  }),
  success: function(response) {
    console.log(response);
  }
});
```

## 升级说明

1. **向下兼容性：** GET接口保持不变，现有的GET请求不受影响
2. **类型安全：** JSON格式提供更好的类型检查和验证
3. **扩展性：** 新的DTO结构便于后续添加新字段
4. **错误处理：** 提供更详细和友好的错误信息
5. **功能增强：** `create-encrypted-qr-image`接口现在支持`businessType`参数