二期 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 经网关一直返：

{"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）：

{
  "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 / #3311
PR: #3308（接入）/ #3312（hotfix + 网关路由）
前置: #3273（#3272 退费说明 CRUD 模块）

4.1 KiB 原始文件 Blame 文件历史 Unescape Escape