docs(changelog): 退费说明融合进资源编辑接口(景区/活动/服务)+旧独立接口节标废弃 (工单#3406 PR#3407)

changelogs-v2/2026-06/03_3389_资源默认收费+收费否禁价格日历+退费说明接入-管理后台.md

@@ -60,6 +60,8 @@ curl -X PUT -H "Authorization: Bearer <token>" -H "Content-Type: application/jso
 
 ## 4. 退费说明接入（景区 / 活动）
 
+> ⚠️ **本节已废弃（2026-06-03 更新）**：退费说明**已改为融合进资源编辑接口**（不再走独立 `/admin/refund-note`），并扩展支持**服务 SERVICE**。前端请按新 changelog `03_3406_退费说明融合进资源编辑接口-景区活动服务-管理后台.md` 接入，**勿按下方独立接口接**。下方内容仅作历史留存。
+
 后端模块早已上线（PR #3273 等），前端编辑页缺 UI，请接入。仅覆盖 **SCENIC / ACTIVITY** 两类。
 
 ### 4.1 接口表

changelogs-v2/2026-06/03_3406_退费说明融合进资源编辑接口-景区活动服务-管理后台.md

@@ -0,0 +1,175 @@
+# 【修改接口·管理后台】退费说明融合进资源编辑接口（景区 / 活动 / 服务）
+
+> **PR**: #3407（工单 #3406）
+> **服务**: hl-resource-service | **更新时间**: 2026-06-03
+>
+> **存放目录**: `changelogs-v2/2026-06/`
+> **影响范围**: 管理后台「资源管理 / 景区·游玩项目·服务」编辑页（基本信息）
+> **状态**: 已合并 dev-v3 + 测试服部署双实例 + API 实测三类通过
+
+---
+
+## ⚠️ 关键说明
+
+退费说明**不再走独立的** `/admin/refund-note` 接口，已**融合进资源编辑接口**——前端在景区/活动/服务编辑页里直接编辑退费说明，随资源一起保存、随详情一起回显，**一个接口搞定**。
+
+- **覆盖三类资源**：景区 SCENIC、游玩项目 ACTIVITY、**服务 SERVICE（本次新增支持）**。
+- **详情** `GET` 响应新增 `refundNote` 字段（未配置为 `null`）。
+- **保存** `POST`(新建) / `PUT`(编辑) 请求体新增 `refundNote` 字段，三态语义见 §3.2。
+- **独立接口 `/admin/refund-note` 仍保留**（向后兼容 + 订单快照内部仍用），但前端**改用融合接口**，不要再调独立接口。
+
+> 替代说明：本文取代 `03_3389_...` changelog 中「退费说明接入（独立接口）」一节。前端**按本文融合接口接入**，勿按旧文的 `/admin/refund-note` 独立接口接。
+
+---
+
+## 1. 背景
+
+退费说明（resource_refund_note）此前是独立 CRUD 模块（`/admin/refund-note`），前端要单独调一套接口维护。运营反馈应在资源编辑页里直接配，故融合进资源的详情/保存接口。同时把适用资源从「景区+活动」扩展到「景区+活动+**服务**」。
+
+---
+
+## 2. 变更清单
+
+| # | 资源 | 详情（回显 refundNote） | 保存（含 refundNote） |
+|---|------|------|------|
+| 1 | 景区 Scenic | GET `/admin/scenic/spot/{scenicId}` | POST `/admin/scenic/spot`、PUT `/admin/scenic/spot/{scenicId}` |
+| 2 | 游玩项目 Activity | GET `/admin/activity/item/{activityId}` | POST `/admin/activity/item`、PUT `/admin/activity/item/{activityId}` |
+| 3 | 服务 Service（**新增**） | GET `/admin/service/item/{serviceId}` | POST `/admin/service/item`、PUT `/admin/service/item/{serviceId}` |
+
+> 列表接口（`/spots`、`/items`）**不返回** refundNote（避免 N+1），退费说明只在单条详情里有。
+
+---
+
+## 3. 接口详情
+
+### 3.1 详情回显
+
+三类资源的详情响应（`ScenicSpotVO` / `ActivityVO` / `ServiceItemVO`）新增字段：
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `refundNote` | object \| null | 退费说明；该资源未配置时为 `null` |
+| `refundNote.noteId` | string | 退费说明 ID（雪花，String 透传防精度丢失） |
+| `refundNote.intro` | string | 资源级备注 |
+| `refundNote.items[]` | array | 退费明细（见 §6.2） |
+| `refundNote.createTime` / `updateTime` | datetime | — |
+
+### 3.2 保存（三态语义）
+
+三类资源的新建/编辑请求体新增 `refundNote`（类型 `RefundNoteEmbedReqVO`，见 §6.1）。后端按 `refundNote` 是否传、items 是否为空分三态处理：
+
+| 入参 refundNote | 行为 |
+|---|---|
+| **不传**（字段缺省 / null） | 保持该资源现有退费说明**不动** |
+| 传了，`items` **为空数组或不传** | **删除**该资源退费说明（清空语义） |
+| 传了，`items` **非空** | **整块 upsert**（连 intro 一起覆盖） |
+
+> 编辑接口是字段级更新：只传 `refundNote` 即可单独维护退费说明，不影响其它字段。
+
+### 3.3 示例（以景区为例，活动/服务同理换路径）
+
+**保存退费说明**（PUT 只传 refundNote，其它字段不动）：
+
+```bash
+curl -X PUT -H "Authorization: Bearer <token>" -H "Content-Type: application/json" \
+  -d '{
+    "refundNote": {
+      "intro": "苔藓为赠送项目，不退费",
+      "items": [
+        { "title": "成人未参加", "amount": 50.00, "settleScope": "PER_PERSON", "unitLabel": "/人", "remark": "仅限成人" }
+      ]
+    }
+  }' \
+  "https://api.test.1814.love:9443/admin/scenic/spot/3001000000000000019"
+```
+
+**详情回显**（GET，data 节选）：
+
+```json
+{
+  "code": 200,
+  "data": {
+    "scenicId": "3001000000000000019",
+    "name": "中俄边境公路（卡线）",
+    "refundNote": {
+      "noteId": "20596378108368322580",
+      "intro": "苔藓为赠送项目，不退费",
+      "items": [
+        { "title": "成人未参加", "amount": 50.00, "settleScope": "PER_PERSON", "settleScopeLabel": "按人", "unitLabel": "/人", "remark": "仅限成人" }
+      ],
+      "createTime": "2026-06-03 17:30:00",
+      "updateTime": "2026-06-03 17:30:00"
+    }
+  }
+}
+```
+
+**清空退费说明**（PUT 传空 items）：
+
+```bash
+curl -X PUT -H "Authorization: Bearer <token>" -H "Content-Type: application/json" \
+  -d '{ "refundNote": { "items": [] } }' \
+  "https://api.test.1814.love:9443/admin/scenic/spot/3001000000000000019"
+# 之后 GET，data.refundNote 为 null
+```
+
+---
+
+## 6. 数据结构
+
+### 6.1 `refundNote` 请求体（`RefundNoteEmbedReqVO`）
+
+前端只传 intro + items，`resourceType` / `resourceId` 由后端从当前资源上下文回填，前端无需传。
+
+| 字段 | 类型 | 必填 | 校验 | 说明 |
+|---|---|---|---|---|
+| `intro` | string | ❌ | `@Size(max=255)` | 资源级备注 |
+| `items` | array | ❌ | `@Size(max=50)` | 退费明细；空/不传=清空 |
+
+### 6.2 退费明细项（`items[]` / `RefundNoteItemVO`）
+
+| 字段 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| `title` | string | ✅ | 展示标题，如「成人未参加」 |
+| `amount` | BigDecimal | ✅ | 退费金额（赠送项目填 0，不可为负） |
+| `unitLabel` | string | ❌ | 展示文案 /人 /团 /辆 |
+| `settleScope` | string | ❌ | 结算粒度 PER_PERSON / PER_TEAM / PER_VEHICLE |
+| `settleScopeLabel` | string | — | 结算粒度中文（出参后端拼字典 order_refund_settle_scope，入参可省） |
+| `remark` | string | ❌ | 备注 |
+| `effectiveFrom` / `effectiveTo` | date | ❌ | 规则生效起止（null=无限制；同传时 from≤to） |
+
+---
+
+## 9. 业务边界
+
+- ✅ **三态语义统一**：不传=不动 / 空 items=删除 / 非空=upsert（三类资源一致）。
+- ✅ **同事务**：退费说明与资源主表在同一事务保存，主表失败则退费说明回滚。
+- ✅ **列表不返回 refundNote**：仅单条详情回显，避免列表 N+1。
+- ✅ **settleScopeLabel 后端拼**：出参按字典 `order_refund_settle_scope` 回填中文，字典异常时 fallback 为 null，不影响主流程。
+- ✅ **独立接口保留**：`/admin/refund-note`（GET/PUT/DELETE）仍可用，订单快照内部仍取退费说明；前端改用融合接口即可。
+- ✅ **items 上限 50**：与独立端点对齐。
+
+---
+
+## 11. 影响评估
+
+- **是否破坏向后兼容**：否（详情新增字段、保存新增可选字段；独立接口未删）。
+- **前端是否必须同步**：是（要在编辑页接入退费说明子表单，改用融合接口）。
+- **影响已有数据**：无（存量退费说明照常，独立接口与融合接口读写同一张表）。
+
+---
+
+## 12. 注意事项
+
+- **改用融合接口**：前端不要再调 `/admin/refund-note` 独立接口（虽保留但即将不维护）。
+- **清空靠空 items**：要删退费说明就传 `refundNote:{items:[]}`，不是不传（不传=不动）。
+- **Long 主键 String**：`refundNote.noteId` 为 String，勿当 Number 解析。
+- **服务也支持了**：服务资源（ServiceItem）本次起可配退费说明，与景区/活动一致。
+
+---
+
+## 13. 关联
+
+- 取代：`03_3389_资源默认收费+收费否禁价格日历+退费说明接入-管理后台.md` 的「退费说明（独立接口）」一节。
+- 后端负责人：@wx
+- 前端对接（管理后台）：mmg