docs(v3): 退费说明接入产品/订单快照 + /admin/refund-note 网关路由修复 (PR #3308/#3312)

2026-06-01 15:38:08 +08:00 · 2026-06-01 15:38:08 +08:00 · 06833500ca
--- a/changelogs-v2/2026-05/30_3307_退费说明接入产品订单快照+网关路由修复_PR3308-3312.md
+++ b/changelogs-v2/2026-05/30_3307_退费说明接入产品订单快照+网关路由修复_PR3308-3312.md
@ -0,0 +1,85 @@
+# 二期 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 模块）