# 前端工作清单：请求/响应参数加密对接

本文档用于前端工程师对接后端新增的“请求/响应参数加密”能力。

## 一、背景与目标

- 后端新增可配置的参数加密能力（默认关闭）。
- 当服务端开启时，前端需按约定对请求体进行加密，并能解密响应体。

## 二、开关与触发规则

- 只有当后端配置开启时才需要启用前端加密。
- 通过请求头 `X-App-Encrypt: 1` 标记本次请求体已加密。
- 如果后端开启“响应加密”，返回会带响应头 `X-App-Encrypt: 1`，响应体为加密载荷。
- 白名单路径（如 `/swagger/`）不会被加解密；前端无需处理。

## 三、加密协议与格式

- 加密算法：AES-GCM。
- 密钥：后端配置 `payload_crypto.secret_key`，需与前端一致。
- 请求/响应体加密后的 JSON 结构：

```json
{ "nonce": "base64", "ciphertext": "base64" }
```

- `nonce` 为 AES-GCM 的随机随机数（Base64），`ciphertext` 为密文（Base64）。

## 四、前端需要实现的功能

1. **请求加密**
   - 当后端开启 `payload_crypto.request.enable` 时，对请求 JSON 体加密。
   - 请求头添加 `X-App-Encrypt: 1`。
   - 发送的请求体替换为加密后的 JSON 结构（`nonce` + `ciphertext`）。

2. **响应解密**
   - 如果响应头包含 `X-App-Encrypt: 1`，则对响应体解密。
   - 解密后得到原始 JSON，再进入业务处理流程。

3. **错误处理**
   - 解密失败时要能捕获并上报（日志/埋点），避免页面卡死。
   - 解密失败可提示“数据解析失败，请重试”。

4. **降级与兼容**
   - 若响应体不是加密结构（未带头或非 JSON），直接走原逻辑。
   - 与后端保持兼容：后端若未开启加密，不应影响现有请求。

## 五、实现建议

- 统一封装在请求拦截器/响应拦截器层：
  - Web：Axios 拦截器。
  - 小程序：封装 `wx.request` 统一处理。
- AES-GCM 需支持：
  - Web: Web Crypto API（`window.crypto.subtle`）。
  - 小程序: 引入可用的 AES-GCM 实现库（需确认平台支持）。
- `nonce` 长度以 AES-GCM 要求为准（通常 12 字节）。

## 六、需要后端确认的信息

- `payload_crypto.secret_key` 的实际值（生产环境）。
- 是否强制 `payload_crypto.request.required`（如果强制，所有接口必须加密）。
- 哪些接口在白名单（默认 `/swagger/`）。

## 七、联调检查清单

- 请求体加密后，后端可以正常解析并返回业务数据。
- 响应解密后，数据结构与未加密时一致。
- 错误场景：
  - 缺少 `X-App-Encrypt` 头且后端强制加密时应收到 400。
  - 非 JSON 响应不应被尝试解密。