mp-java/docs/QrCode_Encryption_Usage.md

加密二维码使用说明

概述

本系统提供了基于token的二维码加密和解密功能，可以安全地生成包含敏感信息的二维码，并设置过期时间。

主要特性

1. AES加密：使用AES对称加密算法保护二维码数据
2. Token机制：每个二维码都有唯一的token作为密钥
3. 过期控制：可设置二维码的有效期（1-1440分钟）
4. Redis存储：token和原始数据存储在Redis中，支持自动过期
5. 数据验证：解密时会验证数据完整性

API接口

1. 生成普通二维码

GET /api/qr-code/create-qr-code?data=https://example.com&size=200x200

参数：

• data: 要编码的数据（必需）
• size: 二维码尺寸，格式：宽x高 或 单个数字（可选，默认200x200）

响应： 直接返回PNG图片流

2. 生成加密二维码（返回JSON）

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

参数：

• data: 要加密的数据（必需）
• width: 二维码宽度（可选，默认200）
• height: 二维码高度（可选，默认200）
• expireMinutes: 过期时间分钟数（可选，默认30，最大1440）

响应示例：

{
  "code": 200,
  "message": "生成加密二维码成功",
  "data": {
    "qrCodeBase64": "iVBORw0KGgoAAAANSUhEUgAA...",
    "token": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
    "originalData": "https://example.com/user/123",
    "expireMinutes": "30"
  }
}

3. 生成加密二维码（返回图片流）

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. 解密二维码数据

POST /api/qr-code/decrypt-qr-data

参数：

• token: token密钥（必需）
• encryptedData: 加密的数据（必需）

响应示例：

{
  "code": 200,
  "message": "解密成功",
  "data": "https://example.com/user/123"
}

5. 验证并解密二维码内容

POST /api/qr-code/verify-and-decrypt-qr

参数：

• qrContent: 二维码扫描得到的完整JSON内容（必需）

二维码内容格式：

{
  "token": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
  "data": "encrypted_data_here",
  "type": "encrypted"
}

响应示例：

{
  "code": 200,
  "message": "验证和解密成功",
  "data": "https://example.com/user/123"
}

6. 检查token是否有效

GET /api/qr-code/check-token?token=a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

响应示例：

{
  "code": 200,
  "message": "检查完成",
  "data": true
}

7. 使token失效

POST /api/qr-code/invalidate-token

参数：

• token: 要使失效的token（必需）

响应示例：

{
  "code": 200,
  "message": "token已失效"
}

使用场景

场景1：用户身份验证二维码

// 生成包含用户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：临时访问链接

// 生成临时访问链接的二维码
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：扫码验证

// 扫描二维码后验证
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分钟之间：过期时间设置不合理