11

2025-09-06 11:58:18 +08:00
commit 8d34972119
1483 changed files with 141190 additions and 0 deletions
--- a/docs/QR_CODE_API_USAGE.md
+++ b/docs/QR_CODE_API_USAGE.md
@@ -0,0 +1,188 @@
+# 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`参数