From 2322a0cd49c9395b847a1cb79b4ea694f9807f9d Mon Sep 17 00:00:00 2001
From: API Changelog Bot <changelog@hulalv.com>
Date: Wed, 3 Jun 2026 15:56:12 +0800
Subject: [PATCH] =?UTF-8?q?docs(changelog):=20=E8=B5=84=E6=BA=90=E9=BB=98?=
 =?UTF-8?q?=E8=AE=A4=E6=94=B6=E8=B4=B9+=E6=94=B6=E8=B4=B9=E5=90=A6?=
 =?UTF-8?q?=E7=A6=81=E4=BB=B7=E6=A0=BC=E6=97=A5=E5=8E=86+=E9=80=80?=
 =?UTF-8?q?=E8=B4=B9=E8=AF=B4=E6=98=8E=E6=8E=A5=E5=85=A5(=E5=B7=A5?=
 =?UTF-8?q?=E5=8D=95#3389=20PR#3392#3395)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 ...收费+收费否禁价格日历+退费说明接入-管理后台.md | 122 ++++++++++++++++++
 1 file changed, 122 insertions(+)
 create mode 100644 changelogs-v2/2026-06/03_3389_资源默认收费+收费否禁价格日历+退费说明接入-管理后台.md

diff --git a/changelogs-v2/2026-06/03_3389_资源默认收费+收费否禁价格日历+退费说明接入-管理后台.md b/changelogs-v2/2026-06/03_3389_资源默认收费+收费否禁价格日历+退费说明接入-管理后台.md
new file mode 100644
index 0000000..75a9f3c
--- /dev/null
+++ b/changelogs-v2/2026-06/03_3389_资源默认收费+收费否禁价格日历+退费说明接入-管理后台.md
@@ -0,0 +1,122 @@
+# 【需求·管理后台】资源默认收费 + 收费=否禁价格日历 + 退费说明接入（景区 / 活动 / 酒店）
+
+> PR: #3392 #3395（工单 #3389）  服务: hl-resource-service | 更新时间: 2026-06-03
+> 存放目录: changelogs-v2/2026-06/  影响范围: 管理后台「资源管理 / 景区·游玩项目·酒店」编辑页
+> 状态: 已合并 dev-v3 + 测试服部署双实例 + API 实测通过
+
+## ⚠️ 关键说明
+
+来自景区编辑页的 3 点反馈，后端已处理（部分是前端没接已实现的接口）：
+
+1. **默认收费**：景区 / 游玩项目 / 酒店新建时「是否收费」默认改为 **收费(1)**。前端开关初始态请置为「收费」开。
+2. **收费=否 → 没有价格日历**：前端在「是否收费=否」时**隐藏价格日历区**；后端已加兜底——给收费=否的景区 / 活动设价会被拒（错误码 **390901**）。
+3. **价格日历不做合并接口**：基本信息与价格日历仍是两个接口，前端保存时**分两次调**（先存基本信息，再批量设价）。
+4. **退费说明**：后端早已实现（`/admin/refund-note`，覆盖景区+活动），**前端编辑页缺这块 UI**，本文补齐接口契约请接入。
+
+服务资源 ServiceItem 的「是否收费」是 `isPaid`+真实定价语义（另有定价校验），**不在本次默认收费范围**，保持现状。
+
+## 1. 默认收费（景区 / 活动 / 酒店）
+
+新建资源不传 `isCharged` 时，后端默认 **1=收费**；前端显式传 `0` 仍尊重为「否」。
+
+| 资源 | 字段 | 新建接口 | 默认值 |
+|------|------|---------|--------|
+| 景区 Scenic | `isCharged` | POST `/admin/scenic/spot` | 1=收费 |
+| 游玩项目 Activity | `isCharged` | POST `/admin/activity/item` | 1=收费 |
+| 酒店 Hotel | `isCharged` | POST `/admin/hotel/item` | 1=收费 |
+
+前端动作：新建表单「是否收费」开关初始置「收费(开)」。编辑回显仍读后端返回的 `isCharged`。
+
+## 2. 收费=否 → 无价格日历
+
+### 2.1 前端
+「是否收费=否」时**隐藏价格日历区**（不展示、不允许设价）。
+
+### 2.2 后端兜底（防脏数据）
+对收费=否（`isCharged=0`）的景区 / 活动调批量设价接口，后端直接拒绝：
+
+```bash
+# 收费=否的景区设价 → 被拦截
+curl -X PUT -H "Authorization: Bearer <token>" -H "Content-Type: application/json" \
+  -d '{"startDate":"2026-07-01","endDate":"2026-07-03","costPrice":100,"status":1}' \
+  "https://api.test.1814.love:9443/admin/scenic/spot/{scenicId}/prices"
+```
+
+响应（测试服实测）：
+
+```json
+{ "code": 390901, "message": "资源未设为收费，不可设置价格日历" }
+```
+
+- 仅拦**批量设价** `PUT /spot/{id}/prices`；查询、改可售状态、清除价格不受影响。
+- 酒店价格日历是 room-type 级，本期不做后端兜底，前端按 2.1 隐藏即可。
+
+## 3. 价格日历保存方式（分两次调，不合并接口）
+
+经确认**不新增合并接口**。前端编辑保存时分两次调用现有接口：
+
+1. 先存基本信息：`PUT /admin/scenic/spot/{scenicId}`
+2. 再批量设价：`PUT /admin/scenic/spot/{scenicId}/prices`（仅在收费=是时调）
+
+## 4. 退费说明接入（景区 / 活动）
+
+后端模块早已上线（PR #3273 等），前端编辑页缺 UI，请接入。仅覆盖 **SCENIC / ACTIVITY** 两类。
+
+### 4.1 接口表
+
+| 操作 | 方法 / 路径 | 参数 |
+|------|------------|------|
+| 查询 | GET `/admin/refund-note` | query: `resourceType`(SCENIC/ACTIVITY) + `resourceId`。未配置返 `data:null`（不报错） |
+| 保存(upsert) | PUT `/admin/refund-note` | body: RefundNoteSaveReqVO（按 resourceType+resourceId upsert 整块） |
+| 删除(软删) | DELETE `/admin/refund-note` | query: `resourceType` + `resourceId`（幂等，未配置也返 code:200 data:false） |
+
+### 4.2 保存请求体（RefundNoteSaveReqVO）
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| resourceType | String | 是 | SCENIC / ACTIVITY |
+| resourceId | Long | 是 | 关联资源 ID |
+| intro | String | 否 | 资源级备注（≤255 字），如「苔藓为赠送项目，不退费」 |
+| items | List | 是 | 退费明细，至少 1 条、最多 50 条 |
+
+items[] 每项（RefundNoteItemVO）：
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| title | String | 是 | 展示标题，如「成人未参加」 |
+| amount | BigDecimal | 是 | 退费金额（赠送项目填 0） |
+| unitLabel | String | 否 | 展示文案 /人 /团 /辆 |
+| settleScope | String | 否 | 结算粒度 PER_PERSON / PER_TEAM / PER_VEHICLE |
+| settleScopeLabel | String | — | 结算粒度中文名（出参后端拼，入参可省） |
+| remark | String | 否 | 备注，如「仅限儿童」 |
+| effectiveFrom | LocalDate | 否 | 规则生效起日（null=无限制） |
+| effectiveTo | LocalDate | 否 | 规则生效止日（null=无限制） |
+
+### 4.3 示例
+
+```bash
+# 查询景区退费说明
+curl -H "Authorization: Bearer <token>" \
+  "https://api.test.1814.love:9443/admin/refund-note?resourceType=SCENIC&resourceId=3001000000000000019"
+
+# 保存
+curl -X PUT -H "Authorization: Bearer <token>" -H "Content-Type: application/json" \
+  -d '{
+    "resourceType": "SCENIC",
+    "resourceId": 3001000000000000019,
+    "intro": "苔藓为赠送项目，不退费",
+    "items": [
+      {"title":"成人未参加","amount":44.00,"unitLabel":"/人","settleScope":"PER_PERSON","remark":"仅限成人"}
+    ]
+  }' \
+  "https://api.test.1814.love:9443/admin/refund-note"
+```
+
+查询响应（RefundNoteRespVO）：`noteId / resourceType / resourceId / intro / items[] / createTime / updateTime`，`noteId` 字符串透传防精度丢失，`settleScopeLabel` 后端回填中文。
+
+## 5. 前端动作清单
+
+1. 景区 / 活动 / 酒店新建表单「是否收费」开关默认置「收费」。
+2. 「是否收费=否」时隐藏价格日历区（编辑页 + 新建页）。
+3. 保存仍分两次调（基本信息 + 价格日历），价格日历仅收费=是时调。
+4. 景区 / 活动编辑页接入「退费说明」模块（GET/PUT/DELETE `/admin/refund-note`）。