# 【后端调整·管理后台】退款详情/列表 actualAmount 字段语义调整（审计 followup）

> **PR**: #3446 | **关联工单**: #3445
> **服务**: hl-order-service-v2（退款）| **更新时间**: 2026-06-04
>
> **存放目录**: `changelogs-v2/2026-06/`
> **影响范围**: 管理后台「退款申请」详情 + 列表的 `actualAmount`（实退/应退额）字段

---

## ⚠️ 关键说明

本批为代码审计 followup 修复，绝大多数为后端内部纠错（无前端影响）。**前端唯一需知**：退款 VO 的 `actualAmount` 字段返回规则调整。

---

## 1. actualAmount 返回规则调整

### 原行为
退款详情/列表 VO 仅在 `REFUNDED`（已退款）状态返回 `actualAmount`，其余状态一律返回 `null`。导致管理端「确认实退」弹窗在 `APPROVED`（已审批待执行）状态下拿不到应退额、无法预填。

### 新行为
按"是否已确定应退/会退款"分组：

| 状态 | actualAmount |
|---|---|
| `APPROVED`（已审批）/ `APPEAL_APPROVED`（申诉通过）/ `REFUNDING`（退款中）/ `REFUNDED`（已退款）| **返回金额**（应退/实退额）|
| `PENDING` / `APPEALING` / `REJECTED` / `APPEAL_REJECTED` / `CANCELLED` | `null`（未确定或不退款）|

### 前端动作
- 「确认实退」弹窗可用 `APPROVED`/`APPEAL_APPROVED`/`REFUNDING` 状态下的 `actualAmount` 预填金额。
- 字段语义：在未到账状态它表示"应退额"，到账后（`REFUNDED`）表示"实退额"；展示文案可按状态区分（如未到账标"应退"、到账标"实退"）。
- 接口路径/结构未变，仅 `actualAmount` 在更多状态下有值。

---

## 2. 其他（无前端影响，仅备案）

本批同时处理了一批后端技术债与规范修复，**均不改变接口契约**，前端无需关注：
- 退款 failReason 回填改走 PaymentService 封装（分层规范）；资源退费说明存在性校验抽 Checker（分层规范）。
- 景区/活动/服务的新建/编辑接口内部把字典翻译（label）的远程调用移出数据库事务（性能，响应结构不变）。
- 收费=否时旧价格日历保留不清理（按产品决策，防误删）。
- 图标库 SVG 安全校验加固（更严格地拒绝危险 SVG，正常图标不受影响）。
- 备品计费口径归一、错误码/常量去重、死代码清理等。

---

## 3. 关联 / 联系人

- **本次 PR**：#3446（Closes #3445）
- **后端负责人**：@wx
- **前端对接（管理后台）**：mmg
