fix(insurance): 充值接口返回支付链接 + 前端弹码/跳转改造说明 (#1725)

changelogs/2026-05/06_fix_insurance_recharge_pay_url.md

@@ -0,0 +1,125 @@
+# fix(insurance): 充值接口返回支付链接 (V2 重构丢失修复)
+
+**日期**: 2026-05-06 18:30
+**通知对象**: @mmg (前端)
+**关联 PR**: wx/HL #1725 (已 merge dev + 测试服部署 + round-trip 6/6 通过)
+**关联工单**: wx/HL #1724
+
+---
+
+## 一、用户反馈
+
+正式环境 `admin.1814.love/insurance/products`「在线充值」弹窗:
+- 输入金额 + 选支付方式(支付宝/微信)
+- 点击「确认充值」
+- `POST /admin/insurance/recharge` 返回 `{"code":200,"message":"成功","data":null,"success":true}`
+- **没有任何充值页面 / 微信二维码 / 支付宝表单**,流程死在弹窗
+
+## 二、根因
+
+V2 重构 (PR #663) 把 Controller 返回从 `Result<Map<String,Object>>` 改成 `Result<Void>` 时,Service `recharge()` 一开始就是 `void`,**根本没解析保游网 `/Pay/GetRechargeData` 响应里的支付链接**。`RechargeRequest` DTO 里 `payType + backUrl` 已声明,但 Controller 没传给 Service,Service 内部硬编码 PayType=33。
+
+## 三、修复
+
+后端改 `recharge` 接口返回支付链接结构体,前端配合改弹码/跳转。
+
+| 文件 | 改动 |
+|---|---|
+| `RechargeRespVO` (新) | 4 字段:payType/payUrl/formHtml/totalFee |
+| `AdminInsuranceController.recharge` | `Result<Void>` → `Result<RechargeRespVO>`,透传 DTO 字段 |
+| `InsuranceManageService.recharge` | 签名改 `(amount, payType, backUrl, adminId, adminName) → RechargeRespVO`,按 payType 解析保游 `Data` |
+| `OrderInsuranceErrorCode` | 加 `RECHARGE_PAY_TYPE_INVALID(540220)` / `RECHARGE_EMPTY_PAY_DATA(540221)` |
+
+## 四、API 改动 (前端必看)
+
+### 请求 `POST /admin/insurance/recharge` (字段未变,提醒强校验)
+
+```json
+{
+  "money": 100.00,           // 必填,0.01 ≤ ≤ 100000
+  "payType": 33,             // 必填!!! 11=支付宝 / 33=微信
+  "backUrl": "https://admin.test.1814.love/insurance/products"  // 选填,支付宝跳回地址
+}
+```
+
+⚠️ **`payType` 现在是后端必填**(DTO `@NotNull`)。旧前端如果没传会返 `code:400 message:"payType: 支付方式不能为空"`,请确认前端选择支付方式后必须把值塞 payload。
+
+### 响应 (新增 data 结构)
+
+**微信扫码 (payType=33)**:
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": {
+    "payType": 33,
+    "payUrl": "weixin://wxpay/bizpayurl?pr=rKqjDdSz3",  // ← 微信扫码 URL
+    "formHtml": null,
+    "totalFee": "0.01"                                    // 单位元字符串
+  },
+  "success": true
+}
+```
+
+**支付宝 (payType=11)**:
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": {
+    "payType": 11,
+    "payUrl": null,
+    "formHtml": "<form id='alipaysubmit' name='alipaysubmit' action='https://mapi.alipay.com/gateway.do?_input_charset=utf-8' method='post'>...<input ... /></form><script>document.forms['alipaysubmit'].submit();</script>",  // ← 完整 HTML 表单
+    "totalFee": null
+  },
+  "success": true
+}
+```
+
+### 业务错误码
+
+| code | message | 触发条件 |
+|---|---|---|
+| 400 | `money: 充值金额最小0.01元` / `充值金额最大100000元` / `充值金额不能为空` | DTO 校验失败 |
+| 400 | `payType: 支付方式不能为空` | DTO `@NotNull` |
+| 540220 | 充值支付方式无效, 只支持 11=支付宝 / 33=微信 | payType 不在 (11, 33) |
+| 540221 | 保游网未返回支付数据 | 第三方异常 |
+| 540210 | 保游网 errorMessage | 保游 isSuccess=false |
+
+## 五、前端处理建议
+
+### 微信扫码 (payType=33)
+
+`payUrl` 是 `weixin://wxpay/bizpayurl?pr=xxx` 协议链接。**用 qrcode 库本地渲染成二维码图片**贴弹窗里,提示「请用微信扫码完成支付」。扫码后微信会自动唤起支付。
+
+```js
+// 推荐用 qrcode (npm: qrcode 或 vue-qr)
+import QRCode from 'qrcode'
+QRCode.toDataURL(resp.data.payUrl, (err, url) => {
+  qrImage.value = url  // <img :src="qrImage" />
+})
+```
+
+### 支付宝 (payType=11)
+
+`formHtml` 是完整 `<form>...</form><script>document.forms['alipaysubmit'].submit();</script>`,**整段塞一个隐藏 div / 临时新窗口**触发自动 submit 跳支付宝网关。
+
+```js
+// 推荐:开新窗口 document.write 整段写入,自动 submit 跳支付宝
+const w = window.open('', '_blank')
+w.document.write(resp.data.formHtml)
+// 或者塞当前页隐藏 iframe + iframe.contentDocument.write
+```
+
+⚠️ formHtml 里包含 `return_url` 字段(后端透传 `backUrl`),用户支付宝付完会跳回该地址。前端建议把 `backUrl` 设为充值页本身,例:`window.location.origin + '/insurance/products'`。
+
+## 六、测试服 round-trip 已验证
+
+- 微信:`data.payUrl=weixin://wxpay/bizpayurl?pr=rKqjDdSz3` 非空 ✓
+- 支付宝:`data.formHtml=<form id='alipaysubmit' action='https://mapi.alipay.com/gateway.do' ...>` 完整 HTML ✓
+- 反例:payType=99 / money=0 / 缺 payType 全部正确报错 ✓
+
+## 七、部署计划
+
+- 测试服:已部署 (deploy task `7e8d25cf` success)
+- 正式环境:等用户合 dev → main 后通知运维部署