# 加密二维码使用说明

## 概述

本系统提供了基于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分钟之间`：过期时间设置不合理