From c36a33ac59a96812e6452f0dbb98126e2a054663 Mon Sep 17 00:00:00 2001 From: API Changelog Bot Date: Tue, 2 Jun 2026 13:38:13 +0800 Subject: [PATCH] =?UTF-8?q?docs(changelog):=20=E9=80=80=E6=AC=BE=E5=88=97?= =?UTF-8?q?=E8=A1=A8=E5=AE=9E=E9=80=80=E9=A2=9D=E4=BB=85=E5=88=B0=E8=B4=A6?= =?UTF-8?q?=E6=98=BE=E7=A4=BA+=E8=AF=A6=E6=83=85=E6=96=B0=E5=A2=9E?= =?UTF-8?q?=E5=A4=B1=E8=B4=A5=E5=8E=9F=E5=9B=A0+=E7=9B=B4=E6=8E=A5?= =?UTF-8?q?=E7=94=B3=E8=AF=89=E5=9B=9E=E6=98=BE=20(#3356/#3357=20PR#3358)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- ...min_order_refund_display_and_failreason.md | 60 +++++++++++++++++++ 1 file changed, 60 insertions(+) create mode 100644 changelogs/2026-06/02_admin_order_refund_display_and_failreason.md diff --git a/changelogs/2026-06/02_admin_order_refund_display_and_failreason.md b/changelogs/2026-06/02_admin_order_refund_display_and_failreason.md new file mode 100644 index 0000000..ceacff5 --- /dev/null +++ b/changelogs/2026-06/02_admin_order_refund_display_and_failreason.md @@ -0,0 +1,60 @@ +# 【管理后台·前端对接】退款列表/详情显示修正:实际退款额仅到账显示、详情新增失败原因、直接申诉回显补全 + +> **类型**: 后端修复 + 接口字段新增(hl-admin 管理后台对接) +> **仓库**: hl-admin(管理后台前端) +> **日期**: 2026-06-02 +> **工单**: #3356 + #3357 ｜ **PR**: #3358 +> **状态**: ✅ 已合并 dev → 同步 dev-v3 → 部署测试服 → **测试服 API 已实测通过** +> **背景**: 处理一笔正式退款时发现退款申请列表/详情的几处显示不准确,本次一并修正。 + +--- + +## 一、退款申请列表「实际退款额」语义修正(行为变化,前端需留意) + +- 接口:`GET /admin/order/refund/list`(分页字段 `page` / `pageSize`) +- **变化**:返回字段 `actualAmount`(实际退款额 = 实际到账金额)现在**仅当 `status=REFUNDED`(微信回调确认退款成功)时才有值**;其余状态(`PENDING`/`APPROVED`/`REFUNDING`/`APPEALING`/`APPEAL_APPROVED`/`REJECTED`/`CANCELLED` 等)一律返回 `null`。 +- **原因**:此前 `actualAmount` 在审批时就预填了,导致「退款中/已取消/申诉中」的单子也显示金额,误以为已退到账。现严格表示「真实到账」。 +- **前端建议**:`actualAmount` 为 `null` 时列内显示「-」即可(与现有空值处理一致)。 + +## 二、退款详情接口新增「失败原因」字段 `failReason` + +- 接口:`GET /admin/order/refund/{applicationId}` +- **新增字段**:`failReason`(String,退款失败原因) + - 退款被微信拒绝/失败时,回显微信返回的原话,例如:`基本账户余额不足，请充值后重新发起` + - 未失败(成功/进行中)时为 `null` +- **前端建议**:详情页在退款记录区域,若 `failReason` 非空则展示「失败原因:xxx」,便于客服/定制师判断为何没退成。 + +```json +// GET /admin/order/refund/{applicationId} 的 data 节选 +{ + "applicationId": "...", + "status": "REFUNDING", + "actualAmount": null, + "failReason": "基本账户余额不足，请充值后重新发起" +} +``` + +## 三、直接申诉的退款单列表回显补全(修复空白) + +- 现象:用户**未先提退款申请、直接发起申诉**产生的退款单,在退款列表里「申请人 / 退款类型 / 已付金额 / 计算退款额」此前全为空(显示「-」)。 +- 修复:这类单子建单时已补全上述字段,列表正常回显。 +- **注意**:仅对**修复后新建**的直接申诉生效;修复前已存在的历史单据仍为空(不回填),前端无需特殊处理。 + +## 四、(后端内部,无需前端对接)退款失败提醒定制师 + +退款彻底失败(如商户号余额不足)时,后端会经通知中心给订单**定制师**发一次企微提醒(含订单/金额/失败原因/待办)。纯后端能力,前端无需改动,知悉即可。 + +--- + +## 五、测试服实测结果(2026-06-02) + +| 用例 | 结果 | +|------|------| +| 列表 18 条:非 REFUNDED 行 actualAmount | ✅ 全部为 null | +| 列表 REFUNDED 行 actualAmount | ✅ 正常有值 | +| 详情接口含 failReason 字段 | ✅ 已返回;构造 FAILED 记录实测回显微信失败原因 | +| Flyway 加列 fail_reason | ✅ 已应用 | + +## 六、联调地址 +- 网关:`https://api.test.1814.love:9443` +- Knife4j 文档同地址,tag「[admin] 退款管理」下可见 `退款申请列表` / `退款申请详情`。