stm32-iot-app/ENCRYPTION_README.md

# 🔐 接口加密功能说明

## 概述

本项目已集成 **RSA + AES 混合加密方案**，参考 `stm32-iot-vben5` 项目实现，为 UniApp 应用提供完整的接口加密能力。

## 快速开始

### 1️⃣ 安装依赖

```bash
npm install crypto-js jsencrypt
```

### 2️⃣ 配置密钥

编辑 `config.js`：

```javascript
export default {
  enableEncrypt: true,  // 开启加密
  rsaPublicKey: `YOUR_PUBLIC_KEY`,  // 配置公钥
  // ...
}
```

### 3️⃣ 使用加密

在 API 调用中添加 `encrypt: true`：

```javascript
export function login(data) {
  return request({
    url: '/login',
    method: 'post',
    data: data,
    encrypt: true  // ⭐ 启用加密
  })
}
```

## 📚 完整文档

| 文档 | 说明 |
|------|------|
| [QUICK_START.md](./QUICK_START.md) | 5分钟快速配置指南 |
| [ENCRYPT_GUIDE.md](./ENCRYPT_GUIDE.md) | 详细使用文档 |
| [INSTALL_DEPENDENCIES.md](./INSTALL_DEPENDENCIES.md) | 依赖安装说明 |
| [CHANGELOG_ENCRYPTION.md](./CHANGELOG_ENCRYPTION.md) | 改造日志 |
| [api/login.encrypt.example.js](./api/login.encrypt.example.js) | 代码示例 |

## 🔑 核心特性

- ✅ **RSA 非对称加密**：安全传输 AES 密钥
- ✅ **AES 对称加密**：高效加密请求/响应数据
- ✅ **自动加密/解密**：对业务代码无侵入
- ✅ **灵活配置**：支持全局/单个接口启用
- ✅ **完善的错误处理**：加密失败有明确提示

## 🎯 适用场景

推荐对以下接口启用加密：

- 🔐 登录/注册
- 🔑 密码修改
- 👤 个人信息修改
- 💳 支付相关
- 🔒 敏感数据传输

## 📁 文件结构

```
stm32-iot-app/
├── utils/
│   ├── request.js      ✅ 已改造（支持加密）
│   └── crypto.js       ✅ 加密工具类
├── config.js           ✅ 加密配置
├── api/
│   └── login.encrypt.example.js  示例代码
├── QUICK_START.md      快速开始
├── ENCRYPT_GUIDE.md    详细指南
└── INSTALL_DEPENDENCIES.md  安装说明
```

## ⚙️ 配置说明

### config.js

| 配置项 | 类型 | 说明 | 默认值 |
|--------|------|------|--------|
| `clientId` | String | 客户端标识 | `e5cd7e...` |
| `enableEncrypt` | Boolean | 全局加密开关 | `false` |
| `rsaPublicKey` | String | RSA 公钥 | 示例密钥 |
| `rsaPrivateKey` | String | RSA 私钥 | `''` |

### 请求配置

| 参数 | 类型 | 说明 |
|------|------|------|
| `encrypt` | Boolean | 是否加密此请求 |

## 🔄 加密流程

### 请求流程

```
生成 AES 密钥 → RSA 加密密钥 → AES 加密数据 → 发送请求
```

### 响应流程

```
接收响应 → RSA 解密密钥 → AES 解密数据 → 返回结果
```

## 📱 平台支持

| 平台 | 支持情况 |
|------|---------|
| H5 | ✅ 完全支持 |
| App (iOS/Android) | ✅ 完全支持 |
| 微信小程序 | ⚠️ 需测试 |
| 其他小程序 | ⚠️ 需测试 |

## ⚠️ 注意事项

1. **仅支持 POST/PUT 请求加密**
2. **公钥必须与后端一致**
3. **小程序端可能需要额外配置**
4. **加密会增加少量性能开销**

## 🐛 故障排除

### 找不到模块？
```bash
npm install crypto-js jsencrypt
```

### 数据解密失败？
检查：
1. 公钥是否正确
2. 后端是否支持加密
3. enableEncrypt 是否为 true

### 小程序不兼容？
参考 [INSTALL_DEPENDENCIES.md](./INSTALL_DEPENDENCIES.md) 中的替代方案

## 📖 示例代码

### 基础使用

```javascript
import request from '@/utils/request'

// 启用加密
export function sensitiveApi(data) {
  return request({
    url: '/api/sensitive',
    method: 'post',
    data: data,
    encrypt: true  // 启用
  })
}

// 不加密
export function normalApi(params) {
  return request({
    url: '/api/normal',
    method: 'get',
    params: params  // GET 请求不支持加密
  })
}
```

### 条件加密

```javascript
// 根据环境决定是否加密
const isDev = process.env.NODE_ENV === 'development'

export function login(data) {
  return request({
    url: '/login',
    method: 'post',
    data: data,
    encrypt: !isDev  // 生产环境加密，开发环境不加密
  })
}
```

## 🔗 相关链接

- RuoYi 官方文档：http://doc.ruoyi.vip/
- UniApp 文档：https://uniapp.dcloud.net.cn/
- crypto-js：https://github.com/brix/crypto-js
- jsencrypt：https://github.com/travist/jsencrypt

## 📞 技术支持

如有问题，请：
1. 查看上述文档
2. 检查控制台日志
3. 联系项目负责人

---

**最后更新：** 2025-12-10  
**版本：** 1.0.0