283 行
8.6 KiB
Markdown
283 行
8.6 KiB
Markdown
# 酒店管理新增「是否收费」字段
|
||
|
||
- **端类型**：管理后台
|
||
- **变更类型**：修改接口
|
||
- **日期**：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）
|