11

docs/QrCode_Encryption_Usage.md

@@ -0,0 +1,215 @@
+# 加密二维码使用说明
+
+## 概述
+
+本系统提供了基于token的二维码加密和解密功能，可以安全地生成包含敏感信息的二维码，并设置过期时间。
+
+## 主要特性
+
+1. **AES加密**：使用AES对称加密算法保护二维码数据
+2. **Token机制**：每个二维码都有唯一的token作为密钥
+3. **过期控制**：可设置二维码的有效期（1-1440分钟）
+4. **Redis存储**：token和原始数据存储在Redis中，支持自动过期
+5. **数据验证**：解密时会验证数据完整性
+
+## API接口
+
+### 1. 生成普通二维码
+
+```http
+GET /api/qr-code/create-qr-code?data=https://example.com&size=200x200
+```
+
+**参数：**
+- `data`: 要编码的数据（必需）
+- `size`: 二维码尺寸，格式：宽x高 或 单个数字（可选，默认200x200）
+
+**响应：** 直接返回PNG图片流
+
+### 2. 生成加密二维码（返回JSON）
+
+```http
+POST /api/qr-code/create-encrypted-qr-code
+```
+
+**参数：**
+- `data`: 要加密的数据（必需）
+- `width`: 二维码宽度（可选，默认200）
+- `height`: 二维码高度（可选，默认200）
+- `expireMinutes`: 过期时间分钟数（可选，默认30，最大1440）
+
+**响应示例：**
+```json
+{
+  "code": 200,
+  "message": "生成加密二维码成功",
+  "data": {
+    "qrCodeBase64": "iVBORw0KGgoAAAANSUhEUgAA...",
+    "token": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
+    "originalData": "https://example.com/user/123",
+    "expireMinutes": "30"
+  }
+}
+```
+
+### 3. 生成加密二维码（返回图片流）
+
+```http
+GET /api/qr-code/create-encrypted-qr-image?data=https://example.com&size=300x300&expireMinutes=60
+```
+
+**参数：**
+- `data`: 要加密的数据（必需）
+- `size`: 二维码尺寸（可选，默认200x200）
+- `expireMinutes`: 过期时间分钟数（可选，默认30）
+
+**响应：** 直接返回PNG图片流，并在响应头中包含token信息
+- `X-QR-Token`: 二维码的token
+- `X-QR-Expire-Minutes`: 过期时间
+
+### 4. 解密二维码数据
+
+```http
+POST /api/qr-code/decrypt-qr-data
+```
+
+**参数：**
+- `token`: token密钥（必需）
+- `encryptedData`: 加密的数据（必需）
+
+**响应示例：**
+```json
+{
+  "code": 200,
+  "message": "解密成功",
+  "data": "https://example.com/user/123"
+}
+```
+
+### 5. 验证并解密二维码内容
+
+```http
+POST /api/qr-code/verify-and-decrypt-qr
+```
+
+**参数：**
+- `qrContent`: 二维码扫描得到的完整JSON内容（必需）
+
+**二维码内容格式：**
+```json
+{
+  "token": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
+  "data": "encrypted_data_here",
+  "type": "encrypted"
+}
+```
+
+**响应示例：**
+```json
+{
+  "code": 200,
+  "message": "验证和解密成功",
+  "data": "https://example.com/user/123"
+}
+```
+
+### 6. 检查token是否有效
+
+```http
+GET /api/qr-code/check-token?token=a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6
+```
+
+**响应示例：**
+```json
+{
+  "code": 200,
+  "message": "检查完成",
+  "data": true
+}
+```
+
+### 7. 使token失效
+
+```http
+POST /api/qr-code/invalidate-token
+```
+
+**参数：**
+- `token`: 要使失效的token（必需）
+
+**响应示例：**
+```json
+{
+  "code": 200,
+  "message": "token已失效"
+}
+```
+
+## 使用场景
+
+### 场景1：用户身份验证二维码
+
+```javascript
+// 生成包含用户ID的加密二维码
+const response = await fetch('/api/qr-code/create-encrypted-qr-code', {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+  body: 'data=user_id:12345&expireMinutes=10'
+});
+
+const result = await response.json();
+// 显示二维码图片：result.data.qrCodeBase64
+// 保存token用于后续验证：result.data.token
+```
+
+### 场景2：临时访问链接
+
+```javascript
+// 生成临时访问链接的二维码
+const accessUrl = 'https://example.com/temp-access?session=abc123';
+const response = await fetch('/api/qr-code/create-encrypted-qr-image?' + 
+  new URLSearchParams({
+    data: accessUrl,
+    size: '250x250',
+    expireMinutes: '5'
+  }));
+
+// 直接使用返回的图片流
+// token信息在响应头 X-QR-Token 中
+```
+
+### 场景3：扫码验证
+
+```javascript
+// 扫描二维码后验证
+const qrContent = '{"token":"...","data":"...","type":"encrypted"}';
+const response = await fetch('/api/qr-code/verify-and-decrypt-qr', {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+  body: 'qrContent=' + encodeURIComponent(qrContent)
+});
+
+const result = await response.json();
+if (result.code === 200) {
+  console.log('原始数据:', result.data);
+} else {
+  console.log('验证失败:', result.message);
+}
+```
+
+## 安全注意事项
+
+1. **token保护**：token是解密的关键，应妥善保管
+2. **过期时间**：根据安全需求设置合适的过期时间
+3. **HTTPS传输**：生产环境中应使用HTTPS传输
+4. **访问控制**：可根据需要添加接口访问权限控制
+5. **日志记录**：建议记录二维码生成和验证的操作日志
+
+## 错误处理
+
+常见错误及处理：
+
+- `token已过期或无效`：二维码已过期，需要重新生成
+- `数据验证失败`：加密数据被篡改或token不匹配
+- `尺寸必须在50-1000像素之间`：二维码尺寸超出允许范围
+- `过期时间必须在1-1440分钟之间`：过期时间设置不合理