docs(changelog): 退款列表实退额仅到账显示+详情新增失败原因+直接申诉回显 (#3356/#3357 PR#3358)

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] 退款管理」下可见 `退款申请列表` / `退款申请详情`。