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

2026-06-03 17:34:52 +08:00

7.7 KiB

原始文件 Blame 文件历史

【修改接口·管理后台】退费说明融合进资源编辑接口（景区 / 活动 / 服务）

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，其它字段不动）：

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 节选）：

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

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

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