wz-golang-server/frontend_payload_crypto_tasks.md

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

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

一、背景与目标

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

二、开关与触发规则

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

三、加密协议与格式

• 加密算法：AES-GCM。
• 密钥：后端配置 payload_crypto.secret_key，需与前端一致。
• 请求/响应体加密后的 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 响应不应被尝试解密。