changelog: 保险充值功能升级 + 余额查询优化

changelogs/2026-03/2026-03-24_insurance_recharge_upgrade.md

@@ -0,0 +1,91 @@
+# 保险模块：充值功能升级 + 余额查询优化
+
+> 日期：2026-03-24 | 服务：hl-insurance-service | 提交：f794175
+
+---
+
+## 一、充值功能升级（前端必改）
+
+### 背景
+保游网充值网站 `www.51baoy.com/recharge` **已关闭**，原来的"充值"按钮（调用 `GET /recharge-url` 获取静态链接跳转）已无法使用。
+
+后端已实现在线充值API，前端需要改为调用新接口。
+
+### 旧接口（已废弃）
+```
+GET /admin/insurance/recharge-url
+```
+> 返回 null，不要再用
+
+### 新接口
+
+```
+POST /admin/insurance/recharge
+Content-Type: application/json
+```
+
+#### 请求参数
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| money | String | 是 | 充值金额（元），如 "100.00" |
+| payType | Integer | 是 | 支付方式：**11**=支付宝扫码，**33**=微信扫码 |
+| backUrl | String | 否 | 支付完成后回调地址（可选） |
+
+#### 请求示例
+```json
+{
+  "money": "500.00",
+  "payType": 11,
+  "backUrl": ""
+}
+```
+
+#### 响应示例
+```json
+{
+  "code": 200,
+  "data": {
+    "payType": 11,
+    "payUrl": "https://...",
+    "formHtml": "<form>...</form>"
+  }
+}
+```
+
+- `payType=11`（支付宝）：返回 `formHtml`，前端渲染为支付页面
+- `payType=33`（微信）：返回 `payUrl`，前端生成二维码展示
+
+### 前端改动建议
+
+**保险产品页面** `/insurance/products` 的"充值"按钮：
+
+1. 点击弹出充值弹窗（el-dialog）
+2. 弹窗内容：
+   - 金额输入框（必填，数字）
+   - 支付方式选择（支付宝/微信，默认支付宝）
+3. 确认后调用 `POST /admin/insurance/recharge`
+4. 根据 payType 展示结果：
+   - 支付宝：新窗口打开 formHtml
+   - 微信：弹窗展示二维码（用 `qrcode` 库将 payUrl 转二维码）
+5. 支付完成后刷新余额
+
+---
+
+## 二、余额查询优化（前端无需改动）
+
+| 优化项 | 之前 | 现在 |
+|--------|------|------|
+| 超时时间 | 最长65秒（token 60s + balance 5s） | 最长10秒（token 5s + balance 5s） |
+| 缓存 | 无，每次进页面都调保游网 | Redis缓存5分钟 |
+| 保游网故障时 | 前端卡死 | 快速返回 null，显示"--" |
+
+**前端无需改动**，接口响应格式不变。
+
+---
+
+## 三、保游网API认证故障（非我方问题）
+
+保游网测试环境 `testapi.51baoy.com` 的 `GetAccessToken` 接口返回500错误（ASP.NET内部异常），导致"同步产品"功能暂时不可用。
+
+**这是保游网服务器问题**，已有的产品数据不受影响。客服电话：4001-882-892。