# 二期 v3：退费说明接入产品详情/订单快照 + 修复 /admin/refund-note 网关路由 404

> **服务**: hl-resource-service / hl-product-service-v2 / hl-order-service-v3 / hl-gateway
> **PR**: #3308（接入）+ #3312（hotfix）
> **Issue**: #3307 / #3311
> **日期**: 2026-06-01
> **影响**: 🟢 新增能力 + 🔴 **修复 #3272 退费说明 admin CRUD 经网关 404 完全不可用**。前端现可正常调 `/admin/refund-note` 维护退费说明；退费说明已接入产品行程节点聚合并在下单时冻进订单快照。

---

## 一、前端必读：`/admin/refund-note` 现在可达了（之前 404）

#3272 交付了「资源退费说明 CRUD」（景区/活动维护退费明细），但**漏配网关路由**，导致 `/admin/refund-note` 经网关一直返：

```json
{"code":404,"message":"接口不存在: /admin/refund-note"}
```

本次已补网关路由。**前端原本对着 #3272 文档写的退费说明 CRUD 弹窗，现在能真正调通了**。三个接口（与 #3272 文档一致，无变化）：

```
GET    /admin/refund-note?resourceType=SCENIC&resourceId=12345   查
PUT    /admin/refund-note                                        upsert 整块
DELETE /admin/refund-note?resourceType=SCENIC&resourceId=12345   软删
```

测试服已实测三个方法经网关全通（200）。仅 `SCENIC` / `ACTIVITY` 两类资源支持。

---

## 二、退费说明接入产品行程节点 + 订单快照（后端能力）

行程节点绑定 SCENIC/ACTIVITY 资源时，产品详情聚合会回填该资源的退费说明；**下单时随产品详情整体冻进 `order_product_snapshot`**，锁定退费条款（资源后改不影响老订单）。

冻结结构（订单产品快照 `itinerary[].nodes[].refundNote`）：

```jsonc
{
  "refundNote": {
    "intro": "苔藓为赠送项目, 不退费",
    "items": [
      {
        "title": "成人未参加",
        "amount": 44.00,
        "unitLabel": "/人",
        "settleScope": "PER_PERSON",
        "settleScopeLabel": "按人",      // 字典中文,冻结即定格
        "remark": "凭票退",
        "effectiveFrom": null,
        "effectiveTo": null
      }
    ]
  }
}
```

仅 SCENIC/ACTIVITY 节点、且资源配过退费说明时才有值，其余节点 / 未配置为 `null`。

---

## 三、暂未做（前端注意）

**订单详情「行程安排 Tab」暂不展示退费说明**。原因：订单 `order_itinerary_node` 表当前下单时不物化（仅后台手动编辑写入），退费说明冻在 `order_product_snapshot` JSON 里。要在行程 Tab 逐节点展示，需后续补「快照→节点叠加」或「下单物化行程」，**不在本期**。本期只保证：①退费说明 admin CRUD 可用 ②退费说明已正确冻进订单快照（数据已锁定，前端展示链路待后续 PR）。

---

## 四、踩坑修复（hotfix #3312）

测试服建单实测发现退费说明进快照恒 null，直查资源接口暴露 **500 ClassCastException**：`JacksonTypeHandler` 反序列化 JSON 列 `List<RefundNoteItem>` 时泛型擦除，运行期元素是 `LinkedHashMap`，用 `List<RefundNoteItem>` 流式处理时 lambda 入口被插 CHECKCAST 在转换前就崩。已改 `List<?>` + `BeanUtil` 兼容（#3272 Converter 同源潜伏 bug 一并修），并补 `LinkedHashMap` 模拟单测锁回归。对前端无感，仅说明为何要 hotfix。

---

## 五、影响评估

- **后端**：资源(DTO+批量查+ClassCast 修)、产品(节点回填)、订单(快照 VO)、网关(路由)；hl-common ResourceDetailDTO 加 refundNote 字段（非破坏）
- **前端**：可立即接入 `/admin/refund-note` CRUD（之前 404 不可用）；订单详情退费说明展示等后续 PR
- **存量订单**：仅新建订单冻结退费说明（快照语义），老订单不回填

---

## 关联

- **Issue**: [#3307](https://git.1814.love:8443/wx/HL/issues/3307) / [#3311](https://git.1814.love:8443/wx/HL/issues/3311)
- **PR**: [#3308](https://git.1814.love:8443/wx/HL/pulls/3308)（接入）/ [#3312](https://git.1814.love:8443/wx/HL/pulls/3312)（hotfix + 网关路由）
- **前置**: [#3273](https://git.1814.love:8443/wx/HL/pulls/3273)（#3272 退费说明 CRUD 模块）