7.2 KiB
7.2 KiB
酒店新增「是否收费」字段（小程序端）
① 接口背景
酒店资源新增「是否收费」属性。小程序端的酒店详情接口和列表接口均已同步透传该字段，供小程序展示酒店是否需要游客付费。字典来源 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}
响应
{
"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}
响应
{
"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，酒店不存在或下架）
{
"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 字段会从响应中消失，小程序侧无感（原本不存在该字段）。
⑫ 注意事项
- 小程序无需配置
sys_yes_no字典，后端已完成翻译并在isChargedLabel中直接返回中文 - 若不需要展示该字段，忽略即可，不影响任何现有功能
- 受缓存影响，运营后台修改后小程序最长延迟 10 分钟可见，属正常现象
⑬ 关联 / 联系人
- Issue：https://git.1814.love:8443/wx/HL/issues/3325
- PR：https://git.1814.love:8443/wx/HL/pulls/3326
- Commit：https://git.1814.love:8443/wx/HL/commit/58afda7f72031b8055dd65805815176f88dfe08c
- 后端负责人：腰苏图（企微 / yst@1814.love）