# 【管理后台·前端对接】退款列表/详情显示修正:实际退款额仅到账显示、详情新增失败原因、直接申诉回显补全

> **类型**: 后端修复 + 接口字段新增(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`(列表 + 详情都返回)

- **新增字段**:`failReason`(String,退款失败原因)
  - 退款被微信拒绝/失败时,回显微信返回的原话,例如:`基本账户余额不足，请充值后重新发起`
  - 未失败(成功/进行中/无失败记录)时为 `null`
- **两个接口都返回**(更新:此前仅详情返回,现列表也返回):
  - 列表:`GET /admin/order/refund/list` —— 每行带 `failReason`,失败过的行有值,其余 `null`
  - 详情:`GET /admin/order/refund/{applicationId}`
- **前端建议**:列表可加「失败原因」列(或在状态旁提示),`failReason` 非空展示「失败原因:xxx」;详情页同样展示。便于运营/客服在列表直接看出哪些单没退成及原因。

```json
// 列表 records[] 每项 / 详情 data 节选
{
  "applicationId": "...",
  "status": "REFUNDING",
  "actualAmount": null,
  "failReason": "基本账户余额不足，请充值后重新发起"
}
```

## 三、直接申诉的退款单列表回显补全(修复空白)

- 现象:用户**未先提退款申请、直接发起申诉**产生的退款单,在退款列表里「申请人 / 退款类型 / 已付金额 / 计算退款额」此前全为空(显示「-」)。
- 修复:这类单子建单时已补全上述字段,列表正常回显。
- **注意**:仅对**修复后新建**的直接申诉生效;修复前已存在的历史单据仍为空(不回填),前端无需特殊处理。

## 四、(后端内部,无需前端对接)退款失败提醒定制师

退款彻底失败(如商户号余额不足)时,后端会经通知中心给订单**定制师**发一次企微提醒(含订单/金额/失败原因/待办)。纯后端能力,前端无需改动,知悉即可。

---

## 五、测试服实测结果(2026-06-02)

| 用例 | 结果 |
|------|------|
| 列表 18 条:非 REFUNDED 行 actualAmount | ✅ 全部为 null |
| 列表 REFUNDED 行 actualAmount | ✅ 正常有值 |
| 详情接口含 failReason 字段 | ✅ 已返回;构造 FAILED 记录实测回显微信失败原因 |
| **列表接口含 failReason 字段** | ✅ 构造 FAILED 记录实测:列表对应行回显失败原因,其余行为 null(单页 1 次批量查,无 N+1) |
| Flyway 加列 fail_reason | ✅ 已应用 |

## 六、联调地址
- 网关:`https://api.test.1814.love:9443`
- Knife4j 文档同地址,tag「[admin] 退款管理」下可见 `退款申请列表` / `退款申请详情`。
