From 52f35eacc8ec78bd8fad2de38084cabc7d4d8a2f Mon Sep 17 00:00:00 2001
From: yaosutu <770858045@qq.com>
Date: Mon, 1 Jun 2026 22:11:56 +0800
Subject: [PATCH] =?UTF-8?q?feat:=20=E9=85=92=E5=BA=97=E6=98=AF=E5=90=A6?=
 =?UTF-8?q?=E6=94=B6=E8=B4=B9=E5=AD=97=E6=AE=B5=20changelog=EF=BC=88?=
 =?UTF-8?q?=E7=AE=A1=E7=90=86=E5=90=8E=E5=8F=B0=20+=20=E5=B0=8F=E7=A8=8B?=
 =?UTF-8?q?=E5=BA=8F=E7=AB=AF=EF=BC=89#3325=20#3326?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../01_3325_酒店是否收费-修改接口-小程序端.md | 243 +++++++++++++++
 .../01_3325_酒店是否收费-修改接口-管理后台.md | 282 ++++++++++++++++++
 2 files changed, 525 insertions(+)
 create mode 100644 changelogs-v2-mp/2026-06/01_3325_酒店是否收费-修改接口-小程序端.md
 create mode 100644 changelogs-v2/2026-06/01_3325_酒店是否收费-修改接口-管理后台.md

diff --git a/changelogs-v2-mp/2026-06/01_3325_酒店是否收费-修改接口-小程序端.md b/changelogs-v2-mp/2026-06/01_3325_酒店是否收费-修改接口-小程序端.md
new file mode 100644
index 0000000..a14b979
--- /dev/null
+++ b/changelogs-v2-mp/2026-06/01_3325_酒店是否收费-修改接口-小程序端.md
@@ -0,0 +1,243 @@
+# 酒店新增「是否收费」字段（小程序端）
+
+- **端类型**：小程序端
+- **变更类型**：修改接口
+- **日期**：2026-06-01
+- **Issue**：[#3325](https://git.1814.love:8443/wx/HL/issues/3325)
+- **PR**：[#3326](https://git.1814.love:8443/wx/HL/pulls/3326)
+- **Commit**：[58afda7](https://git.1814.love:8443/wx/HL/commit/58afda7f72031b8055dd65805815176f88dfe08c)
+- **后端负责人**：腰苏图（yst@1814.love）
+
+---
+
+## ① 接口背景
+
+酒店资源新增「是否收费」属性。小程序端的酒店详情接口和列表接口均已同步透传该字段，供小程序展示酒店是否需要游客付费。字典来源 `sys_yes_no`，后端已配置并完成翻译，小程序无需任何字典配置。
+
+---
+
+## ② 变更清单
+
+| 接口 | 方法 | 路径 | 变更内容 |
+|------|------|------|----------|
+| 酒店详情 | GET | `/mp/hotel/{hotelId}` | 出参新增 `isCharged` + `isChargedLabel` |
+| 酒店列表 | GET | `/mp/hotel/list` | 出参新增 `isCharged` + `isChargedLabel` |
+
+所有变更均为**向后兼容新增字段**，小程序现有调用代码无需修改。
+
+---
+
+## ③ 接口详情
+
+| 项目 | 说明 |
+|------|------|
+| **认证方式** | 小程序 JWT Token，请求头 `Authorization: Bearer {mp_token}` |
+| **幂等性** | GET 查询，天然幂等 |
+| **限流** | 无单独限流配置，走网关全局限流 |
+| **缓存** | 详情接口缓存 300 秒（`hotel:detail:{id}`），列表接口缓存 600 秒（`hotel:list:{keyword}:{city}:{starLevel}:{page}:{pageSize}`）。新字段随正常缓存刷新即可，无需额外处理 |
+| **权限** | 小程序用户，已登录状态 |
+
+---
+
+## ④ 接口入参
+
+### GET `/mp/hotel/{hotelId}` 详情
+
+| 参数名 | 类型 | 必填 | 说明 |
+|--------|------|------|------|
+| hotelId | Long | 是 | 酒店 ID（路径参数） |
+
+### GET `/mp/hotel/list` 列表
+
+| 参数名 | 类型 | 必填 | 默认值 | 说明 |
+|--------|------|------|--------|------|
+| keyword | String | 否 | - | 关键词搜索 |
+| city | String | 否 | - | 城市筛选 |
+| starLevel | String | 否 | - | 星级筛选（字典: hotel_star_level） |
+| page | Integer | 否 | 1 | 页码 |
+| pageSize | Integer | 否 | 20 | 每页条数 |
+
+> 入参无变化，以上为完整入参文档。
+
+---
+
+## ⑤ 出参字段
+
+### GET `/mp/hotel/{hotelId}` 详情（`MpHotelDetailVO`，新增字段）
+
+| 字段名 | 类型 | 说明 | 可能为 null |
+|--------|------|------|-------------|
+| isCharged | Integer | 是否收费，1=是 0=否 | 否（DB 默认 0） |
+| isChargedLabel | String | 是否收费中文文本，取自字典 sys_yes_no（"是"/"否"） | 是（字典缺失时为 null） |
+
+### GET `/mp/hotel/list` 列表（`MpHotelListItemVO`，新增字段）
+
+| 字段名 | 类型 | 说明 | 可能为 null |
+|--------|------|------|-------------|
+| isCharged | Integer | 是否收费，1=是 0=否 | 否（DB 默认 0） |
+| isChargedLabel | String | 是否收费中文文本，取自字典 sys_yes_no（"是"/"否"） | 是（字典缺失时为 null） |
+
+---
+
+## ⑥ 枚举 / 数据字典
+
+### sys_yes_no 字典（后端已配置，小程序无需维护）
+
+| 字典值（isCharged） | 中文标签（isChargedLabel） | 说明 |
+|--------------------|-----------------------------|------|
+| 1 | 是 | 该酒店收费 |
+| 0 | 否 | 该酒店免费 |
+
+> `isChargedLabel` 由后端查字典自动翻译并返回，小程序可直接展示。若字典配置异常（不正常情况），该字段返回 null。
+
+---
+
+## ⑦ 错误码
+
+| 错误码 | HTTP 状态 | 场景 |
+|--------|-----------|------|
+| 401 | 401 | 未登录或 Token 失效 |
+| 404 | 404 | 酒店 ID 不存在、已删除或已下架 |
+
+---
+
+## ⑧ 示例
+
+### 8.1 典型成功 — 获取收费酒店详情
+
+**请求**
+```
+GET /mp/hotel/1928000000000001
+Authorization: Bearer {mp_token}
+```
+
+**响应**
+```json
+{
+  "code": 200,
+  "msg": "成功",
+  "data": {
+    "hotelId": "1928000000000001",
+    "name": "丽江悦榕庄",
+    "subtitle": "古城边的世外桃源",
+    "hotelType": "HOTEL",
+    "isCharged": 1,
+    "isChargedLabel": "是",
+    "status": 1,
+    "city": "丽江市"
+  }
+}
+```
+
+### 8.2 边界情况 — 列表中混合收费/免费酒店（均返回 isCharged + isChargedLabel）
+
+**请求**
+```
+GET /mp/hotel/list?city=丽江市&page=1&pageSize=20
+Authorization: Bearer {mp_token}
+```
+
+**响应**
+```json
+{
+  "code": 200,
+  "msg": "成功",
+  "data": {
+    "total": 2,
+    "list": [
+      {
+        "hotelId": "1928000000000001",
+        "name": "丽江悦榕庄",
+        "isCharged": 1,
+        "isChargedLabel": "是"
+      },
+      {
+        "hotelId": "1928000000000002",
+        "name": "团队免费住宿点",
+        "isCharged": 0,
+        "isChargedLabel": "否"
+      }
+    ]
+  }
+}
+```
+
+### 8.3 业务失败 — 访问已下架酒店
+
+**请求**
+```
+GET /mp/hotel/1928000000000099
+Authorization: Bearer {mp_token}
+```
+
+**响应**（404，酒店不存在或下架）
+```json
+{
+  "code": 404,
+  "msg": "酒店不存在",
+  "data": null
+}
+```
+
+---
+
+## ⑨ 业务边界
+
+**适用场景**：
+- 小程序酒店详情页展示"是否收费"信息
+- 小程序酒店列表卡片可展示收费状态，帮助用户快速识别
+
+**不适用场景**：
+- `isCharged` 仅为展示属性，不影响小程序下单流程或费用计算
+- 列表接口不支持按 `isCharged` 筛选
+
+**特殊边界**：
+- 历史存量酒店（PR #3326 上线前创建）`isCharged` 默认为 0，`isChargedLabel` 返回 "否"
+- 该字段受缓存影响：管理后台修改 isCharged 后，小程序侧缓存最多 5-10 分钟后自动刷新（详情 300s / 列表 600s）
+
+---
+
+## ⑩ 修改前后对比
+
+### 字段级对比
+
+**出参（详情 + 列表）**
+
+| 字段名 | 变更前 | 变更后 |
+|--------|--------|--------|
+| isCharged | 不存在 | ✨ 新增，Integer，1=是/0=否 |
+| isChargedLabel | 不存在 | ✨ 新增，String，字典翻译文本，可能为 null |
+
+### 行为级对比
+
+| 行为 | 变更前 | 变更后 |
+|------|--------|--------|
+| 酒店详情接口 | 无收费信息 | 新增 isCharged + isChargedLabel |
+| 酒店列表接口 | 无收费信息 | 新增 isCharged + isChargedLabel |
+
+---
+
+## ⑪ 影响评估 / 回滚
+
+**破坏兼容性**：无，新增字段，现有小程序代码可忽略不用。
+
+**前端同步上线**：无强制要求，可选接入展示。
+
+**回滚方案**：若后端回滚，`isCharged` 和 `isChargedLabel` 字段会从响应中消失，小程序侧无感（原本不存在该字段）。
+
+---
+
+## ⑫ 注意事项
+
+1. 小程序**无需**配置 `sys_yes_no` 字典，后端已完成翻译并在 `isChargedLabel` 中直接返回中文
+2. 若不需要展示该字段，忽略即可，不影响任何现有功能
+3. 受缓存影响，运营后台修改后小程序最长延迟 10 分钟可见，属正常现象
+
+---
+
+## ⑬ 关联 / 联系人
+
+- **Issue**：[https://git.1814.love:8443/wx/HL/issues/3325](https://git.1814.love:8443/wx/HL/issues/3325)
+- **PR**：[https://git.1814.love:8443/wx/HL/pulls/3326](https://git.1814.love:8443/wx/HL/pulls/3326)
+- **Commit**：[https://git.1814.love:8443/wx/HL/commit/58afda7f72031b8055dd65805815176f88dfe08c](https://git.1814.love:8443/wx/HL/commit/58afda7f72031b8055dd65805815176f88dfe08c)
+- **后端负责人**：腰苏图（企微 / yst@1814.love）
diff --git a/changelogs-v2/2026-06/01_3325_酒店是否收费-修改接口-管理后台.md b/changelogs-v2/2026-06/01_3325_酒店是否收费-修改接口-管理后台.md
new file mode 100644
index 0000000..8f490bd
--- /dev/null
+++ b/changelogs-v2/2026-06/01_3325_酒店是否收费-修改接口-管理后台.md
@@ -0,0 +1,282 @@
+# 酒店管理新增「是否收费」字段
+
+- **端类型**：管理后台
+- **变更类型**：修改接口
+- **日期**：2026-06-01
+- **Issue**：[#3325](https://git.1814.love:8443/wx/HL/issues/3325)
+- **PR**：[#3326](https://git.1814.love:8443/wx/HL/pulls/3326)
+- **Commit**：[58afda7](https://git.1814.love:8443/wx/HL/commit/58afda7f72031b8055dd65805815176f88dfe08c)
+- **后端负责人**：腰苏图（yst@1814.love）
+
+---
+
+## ① 接口背景
+
+酒店资源新增「是否收费」属性，用于在管理后台创建/编辑酒店时标记该酒店是否需要游客付费。该字段同步透出到列表和详情接口，便于运营人员在列表页一眼识别收费/免费酒店。字典来源 `sys_yes_no`，后端已配置，前端无需额外配置。
+
+---
+
+## ② 变更清单
+
+| 接口 | 方法 | 路径 | 变更内容 |
+|------|------|------|----------|
+| 创建酒店 | POST | `/admin/hotel/item` | 入参新增 `isCharged`（Integer，默认 0） |
+| 更新酒店 | PUT | `/admin/hotel/item/{hotelId}` | 入参新增 `isCharged`（Integer，可选） |
+| 酒店详情 | GET | `/admin/hotel/item/{hotelId}` | 出参新增 `isCharged` + `isChargedLabel` |
+| 酒店列表 | GET | `/admin/hotel/items` | 出参新增 `isCharged` + `isChargedLabel` |
+
+所有变更均为**向后兼容新增字段**，不涉及字段改名或删除。
+
+---
+
+## ③ 接口详情
+
+| 项目 | 说明 |
+|------|------|
+| **认证方式** | 管理后台 JWT Token，请求头 `Authorization: Bearer {token}` |
+| **幂等性** | POST 创建非幂等；PUT 更新幂等（相同 hotelId 可重复调用） |
+| **限流** | 无单独限流配置，走网关全局限流 |
+| **权限** | 管理员角色，普通前端用户无访问权限 |
+
+---
+
+## ④ 接口入参
+
+### 4.1 路径参数 / Query 参数
+
+**PUT `/admin/hotel/item/{hotelId}`**
+
+| 参数名 | 类型 | 必填 | 说明 |
+|--------|------|------|------|
+| hotelId | Long | 是 | 酒店 ID（路径参数） |
+
+**GET `/admin/hotel/items`**（列表，原有参数不变，无新增查询参数）
+
+### 4.2 请求体字段（新增字段，含于已有请求体中）
+
+**POST `/admin/hotel/item`**（`HotelCreateRequest`，新增字段）
+
+| 字段名 | 类型 | 必填 | 校验规则 | 默认值 | 说明 |
+|--------|------|------|----------|--------|------|
+| isCharged | Integer | 否 | Min=0, Max=1 | 0 | 是否收费，1=是 0=否 |
+
+**PUT `/admin/hotel/item/{hotelId}`**（`HotelUpdateRequest`，新增字段）
+
+| 字段名 | 类型 | 必填 | 校验规则 | 默认值 | 说明 |
+|--------|------|------|----------|--------|------|
+| isCharged | Integer | 否 | Min=0, Max=1 | null（不传则不修改） | 是否收费，1=是 0=否 |
+
+---
+
+## ⑤ 出参字段
+
+### GET `/admin/hotel/item/{hotelId}` 详情（`HotelVO`，新增字段）
+
+| 字段名 | 类型 | 说明 | 可能为 null |
+|--------|------|------|-------------|
+| isCharged | Integer | 是否收费，1=是 0=否 | 否（DB 默认 0） |
+| isChargedLabel | String | 是否收费中文文本，取自字典 sys_yes_no（"是"/"否"） | 是（字典缺失时为 null） |
+
+### GET `/admin/hotel/items` 列表（`HotelListVO`，新增字段）
+
+| 字段名 | 类型 | 说明 | 可能为 null |
+|--------|------|------|-------------|
+| isCharged | Integer | 是否收费，1=是 0=否 | 否（DB 默认 0） |
+| isChargedLabel | String | 是否收费中文文本，取自字典 sys_yes_no（"是"/"否"） | 是（字典缺失时为 null） |
+
+---
+
+## ⑥ 枚举 / 数据字典
+
+### sys_yes_no 字典（后端已配置，前端无需维护）
+
+| 字典值（isCharged） | 中文标签（isChargedLabel） | 说明 |
+|--------------------|-----------------------------|------|
+| 1 | 是 | 该酒店收费 |
+| 0 | 否 | 该酒店免费 |
+
+> `isChargedLabel` 由后端查字典自动翻译，前端可直接展示。若字典配置缺失（不正常情况），该字段返回 null。
+
+---
+
+## ⑦ 错误码
+
+| 错误码 | HTTP 状态 | 场景 |
+|--------|-----------|------|
+| 400 | 400 | `isCharged` 传入非 0/1 的值（如 2、-1），Bean Validation 失败 |
+| 401 | 401 | 未登录或 Token 失效 |
+| 403 | 403 | 无管理员权限 |
+| 404 | 404 | 酒店 ID 不存在或已删除 |
+
+---
+
+## ⑧ 示例
+
+### 8.1 典型成功 — 创建收费酒店
+
+**请求**
+```
+POST /admin/hotel/item
+Authorization: Bearer {admin_token}
+Content-Type: application/json
+
+{
+  "name": "丽江悦榕庄",
+  "hotelType": "HOTEL",
+  "address": "束河古镇悦榕路1号",
+  "longitude": 100.2134,
+  "latitude": 26.8721,
+  "isCharged": 1
+}
+```
+
+**响应**
+```json
+{
+  "code": 200,
+  "msg": "成功",
+  "data": {
+    "hotelId": "1928000000000001",
+    "name": "丽江悦榕庄",
+    "isCharged": 1,
+    "isChargedLabel": "是",
+    "status": 0
+  }
+}
+```
+
+### 8.2 边界情况 — 不传 isCharged（使用默认值 0）
+
+**请求**
+```
+POST /admin/hotel/item
+Authorization: Bearer {admin_token}
+Content-Type: application/json
+
+{
+  "name": "团队免费住宿点",
+  "hotelType": "HOSTEL",
+  "address": "丽江古城区某路1号",
+  "longitude": 100.2200,
+  "latitude": 26.8800
+}
+```
+
+**响应**（isCharged 默认为 0）
+```json
+{
+  "code": 200,
+  "msg": "成功",
+  "data": {
+    "hotelId": "1928000000000002",
+    "name": "团队免费住宿点",
+    "isCharged": 0,
+    "isChargedLabel": "否",
+    "status": 0
+  }
+}
+```
+
+### 8.3 业务失败 — isCharged 传入越界值
+
+**请求**
+```
+POST /admin/hotel/item
+Authorization: Bearer {admin_token}
+Content-Type: application/json
+
+{
+  "name": "测试酒店",
+  "hotelType": "HOTEL",
+  "address": "测试地址",
+  "longitude": 100.0,
+  "latitude": 26.0,
+  "isCharged": 2
+}
+```
+
+**响应**（400 参数校验失败）
+```json
+{
+  "code": 400,
+  "msg": "是否收费取值范围为0或1",
+  "data": null
+}
+```
+
+---
+
+## ⑨ 业务边界
+
+**适用场景**：
+- 创建新酒店时，可设置是否收费标记（不传默认不收费）
+- 编辑已有酒店时，可随时修改是否收费状态（传 null 或不传则保持原值不变）
+- 列表和详情页均可展示该字段，用于运营人员快速判断酒店性质
+
+**不适用场景**：
+- 该字段仅用于标记属性，不影响产品定价逻辑（定价由费用项管理）
+- 不用于权限控制，仅作展示属性
+
+**特殊边界**：
+- 历史存量酒店（PR #3326 上线前创建的）`isCharged` 默认为 0（否），`isChargedLabel` 返回 "否"
+- PUT 更新时若不传 `isCharged` 字段，该字段值保持不变（不会被清零）
+- `isChargedLabel` 为 null 时属于字典配置异常，非正常情况
+
+---
+
+## ⑩ 修改前后对比
+
+### 字段级对比
+
+**入参（POST 创建 / PUT 更新）**
+
+| 字段名 | 变更前 | 变更后 |
+|--------|--------|--------|
+| isCharged | 不存在 | ✨ 新增，Integer，可选，默认 0（Create），可 null（Update） |
+
+**出参（详情 + 列表）**
+
+| 字段名 | 变更前 | 变更后 |
+|--------|--------|--------|
+| isCharged | 不存在 | ✨ 新增，Integer，1=是/0=否 |
+| isChargedLabel | 不存在 | ✨ 新增，String，字典翻译文本，可能为 null |
+
+### 行为级对比
+
+| 行为 | 变更前 | 变更后 |
+|------|--------|--------|
+| 创建酒店 | 无收费标记 | 可设置 isCharged，默认 0 |
+| 列表展示 | 无收费信息 | 新增 isCharged + isChargedLabel |
+| 详情展示 | 无收费信息 | 新增 isCharged + isChargedLabel |
+
+---
+
+## ⑪ 影响评估 / 回滚
+
+**破坏兼容性**：无，新增字段均为可选，现有调用代码无需修改即可正常运行。
+
+**前端同步上线**：
+- 创建/编辑表单：可选接入 `isCharged` 开关/选择器，不接入则默认 0
+- 列表/详情页：可选展示 `isChargedLabel`，不展示也不影响功能
+
+**回滚方案**：
+- 若需回滚，执行 `ALTER TABLE hotel DROP COLUMN is_charged;` 并回退服务部署
+- 前端零改动时回滚对前端无感
+
+---
+
+## ⑫ 注意事项
+
+1. `isChargedLabel` 依赖字典 `sys_yes_no` 配置，后端已配置好，前端**不需要**维护字典表
+2. 列表接口返回 `isChargedLabel` 纯粹为展示便利，前端也可用 `isCharged` 值自行映射（1→"是"，0→"否"）
+3. PUT 更新时 `isCharged` 不传（null）表示不修改，区别于传 `0`（明确设置为否）
+4. 历史数据库存量记录 `is_charged` 列已通过 DDL 添加默认值 0，无历史数据问题
+
+---
+
+## ⑬ 关联 / 联系人
+
+- **Issue**：[https://git.1814.love:8443/wx/HL/issues/3325](https://git.1814.love:8443/wx/HL/issues/3325)
+- **PR**：[https://git.1814.love:8443/wx/HL/pulls/3326](https://git.1814.love:8443/wx/HL/pulls/3326)
+- **Commit**：[https://git.1814.love:8443/wx/HL/commit/58afda7f72031b8055dd65805815176f88dfe08c](https://git.1814.love:8443/wx/HL/commit/58afda7f72031b8055dd65805815176f88dfe08c)
+- **后端负责人**：腰苏图（企微 / yst@1814.love）