docs: 通知前端接入酒店支付方式与询房话术

2026-07-10 18:27:10 +08:00 · 2026-07-10 18:27:10 +08:00 · 1f77becb70
--- a/changelogs-v2/2026-07/55_4893_酒店支付方式快照与订房确认话术-前端待处理-管理后台.md
+++ b/changelogs-v2/2026-07/55_4893_酒店支付方式快照与订房确认话术-前端待处理-管理后台.md
@ -0,0 +1,248 @@
+# 酒店支付方式快照与订房确认话术
+
+- 状态：frontend-todo
+- 后端工单：[wx/HL#4893](https://git.1814.love:8443/wx/HL/issues/4893)
+- 服务：`hl-resource-service`、`hl-order-service-v3`
+- 日期：2026-07-10
+- 影响端：管理后台 `hl-ui-v2.1` 酒店资源、房务选酒店、配房修改、复制询房话术
+- 前端代码状态：后端本次未修改 `hl-ui`，以下项目需由前端正式接入
+
+## 一、关键结论
+
+| 项目 | 最新口径 |
+| --- | --- |
+| 前端显示名 | 支付方式 |
+| 后端字段 | 统一复用 `settleType` |
+| 字典 | `resource_settle_type` |
+| 字典值 | `cash` / `sign` / `company` |
+| 删除字段 | 酒店及房务链路不再使用 `paymentMode` |
+| 配房保存 | `settleType` 与协议价、结算价一样保存到配房快照 |
+| 写回资源 | 只有显式传 `syncSettleType=true` 才写回酒店资源，默认不写回 |
+| 复制动作 | 仍是原“复制询房话术”，不要新增第二个“订房确认书”按钮 |
+| 文案来源 | 直接复制后端 `messageBody`，前端不再二次拼接或补酒店名 |
+
+支付方式文案映射：
+
+| `settleType` | 话术第 1 行 |
+| --- | --- |
+| `cash` | `领队前台现付，价格保密。` |
+| `sign` | `签单，价格保密。` |
+| `company` | `公司付款，价格保密。` |
+
+## 二、酒店资源配置
+
+### 涉及接口
+
+| 接口 | 方法 | 变化 |
+| --- | --- | --- |
+| `/admin/hotel/item` | POST | 创建请求新增 3 个配置字段 |
+| `/admin/hotel/item/{hotelId}` | GET | 详情响应新增 3 个配置字段 |
+| `/admin/hotel/item/{hotelId}` | PUT | 更新请求新增 3 个配置字段 |
+
+### 新增字段
+
+| 字段 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `breakfastIncluded` | Boolean | 否 | 是否含早餐；新建未传时兼容从设施“早餐”推断 |
+| `canIssueInvoice` | Boolean | 否 | 是否可开发票；默认 `false` |
+| `bookingReplyContacts` | String | 否 | 订房回复联系人，可填写多人展示文本，最长 255 |
+
+示例：
+
+```json
+{
+  "settleType": "cash",
+  "breakfastIncluded": true,
+  "canIssueInvoice": true,
+  "bookingReplyContacts": "哈撒尔，原景销售李苗"
+}
+```
+
+前端要求：
+
+- 酒店资源表单继续用 `settleType`，资源管理页面显示名可保持“结算方式”。
+- 增加“含早餐”“可开发票”“订房回复联系人”三个配置控件。
+- 不再读取、提交或展示酒店 `paymentMode`。
+- 存量早餐已由后端按设施包含“早餐”或酒店标签“含早餐”兼容；发票默认否；回复联系人为空时话术回退 `contactPerson`。
+
+## 三、房务选酒店与配房快照
+
+### 候选与详情读取
+
+| 接口 | 响应字段 | 前端处理 |
+| --- | --- | --- |
+| `GET /v3/admin/hotel-candidates` | `items[].settleType` | 选酒店弹窗“支付方式”默认值 |
+| `GET /v3/admin/house/hotels` | `records[].settleType` | 房务酒店列表展示/筛选 |
+| `GET /admin/house/orders/{orderId}` | `itinerary[].assignments[].settleType` | 已保存配房的支付方式快照 |
+
+候选、列表及详情中的 `paymentMode` 已删除，前端类型和兼容代码同步删除。
+
+### 提交或替换配房
+
+接口：
+
+```http
+POST /v3/admin/order/hotel-requirements/{requirementId}/assignments
+```
+
+`items[]` 新增：
+
+```json
+{
+  "hotelId": "200001",
+  "roomTypeId": "300001",
+  "settleType": "cash",
+  "syncSettleType": false
+}
+```
+
+| 字段 | 类型 | 必填 | 约束 | 说明 |
+| --- | --- | --- | --- | --- |
+| `settleType` | String | 否 | `cash/sign/company` | 不传时取酒店资源当前配置并冻结到快照 |
+| `syncSettleType` | Boolean | 否 | 默认 `false` | `true` 才把本次支付方式写回酒店资源 |
+
+### 修改单条配房
+
+接口：
+
+```http
+PUT /v3/admin/order/assignments/{assignmentId}
+```
+
+请求体同样支持：
+
+```json
+{
+  "settleType": "sign",
+  "syncSettleType": true
+}
+```
+
+交互要求：
+
+- `PickHotelModal.vue` 增加“支付方式”，默认带出候选酒店的 `settleType`，允许修改。
+- 选中项必须保留 `settleType`，提交配房时透传，不能只保留价格字段。
+- 与协议价、结算价一致，支付方式写回资源必须由用户显式确认；未确认传 `false`。
+- 编辑已配房记录时，默认使用 `assignments[].settleType`；旧快照为空时可回退当前候选酒店的 `settleType`。
+- 支付方式不做金额转换，也不要使用 `Number()`。
+
+## 四、复制询房话术
+
+接口：
+
+```http
+POST /v3/admin/order/inquiry/preview
+```
+
+### 已配房场景请求
+
+复制按钮当前只在“已配房/询房中”后可用，因此必须把订单和配房 ID 传给后端：
+
+```json
+{
+  "hotelId": "200001",
+  "orderId": "30456",
+  "assignmentId": "99999"
+}
+```
+
+后端按以下优先级生成：
+
+| 内容 | 优先级 |
+| --- | --- |
+| 团号 | `order.teamNo` → `order.orderNo` → `待补充` |
+| 日期、房型、间数 | 配房快照 → 请求兜底字段 |
+| 支付方式 | 配房 `settleType` 快照 → 酒店资源 `settleType` → `cash` |
+| 核房电话 | `roomSharePhone` → `contactPhone` → `待补充` |
+| 回复联系人 | `bookingReplyContacts` → `contactPerson` → `待补充` |
+| 备注 | 酒店标签用 `、` 连接；无标签为 `无` |
+
+### 未保存配房的兼容请求
+
+只有确实拿不到 `assignmentId` 时，才使用以下兼容参数：
+
+```json
+{
+  "hotelId": "200001",
+  "orderId": "30456",
+  "stayDate": "2026-08-11",
+  "roomCount": 2,
+  "roomCategory": "DOUBLE_BED"
+}
+```
+
+旧参数 `nights`、`messageBody` 不再参与新模板生成，前端应移除。
+
+### 响应与精确文案
+
+```json
+{
+  "code": 200,
+  "success": true,
+  "data": {
+    "messageBody": "呼籁旅行 - 订房确认书：\n团号：ZK-835-260808-3563\n日期：8.11\n房型：全景大床2间\n备注：含早餐、草原景观\n1.领队前台现付，价格保密。\n2.含早含发票\n3.核房电话：0470-8290955\n辛苦确认后回复 @哈撒尔，原景销售李苗",
+    "contactName": "王经理",
+    "contactWechat": "hotel-wx"
+  }
+}
+```
+
+复制结果必须保持为：
+
+```text
+呼籁旅行 - 订房确认书：
+团号：ZK-835-260808-3563
+日期：8.11
+房型：全景大床2间
+备注：含早餐、草原景观
+1.领队前台现付，价格保密。
+2.含早含发票
+3.核房电话：0470-8290955
+辛苦确认后回复 @哈撒尔，原景销售李苗
+```
+
+### 当前前端必须修改的兼容逻辑
+
+当前 `useHousekeeperInquiryCopy.js` 会在后端文案不含酒店名时调用 `buildInquiryPhrase()` 重拼旧话术。新固定文案按需求本来就不包含酒店名，因此必须改为：
+
+- 成功响应后直接复制 `res.messageBody`。
+- 不再检查文案是否包含酒店名。
+- 不再用 `buildInquiryPhrase()` 二次拼接。
+- 保留现有剪贴板失败后的“手动复制询房话术”弹窗。
+- 按钮仍叫“复制询房话术”，不要增加第二个复制动作。
+
+## 五、删除 `paymentMode` 的影响面
+
+以下酒店/房务契约不再返回或接收 `paymentMode`：
+
+| 范围 | 处理 |
+| --- | --- |
+| 房务酒店列表请求和响应 | 删除 `paymentMode` 筛选及展示 |
+| 酒店候选响应 | 删除 `paymentMode` |
+| 酒店基础信息/扩展信息 | 删除 `paymentMode` |
+| 签单与打印行程单酒店块 | 删除 `paymentMode`，保留 `settleType` 中文翻译 |
+
+注意：订单主单的 `order_main.paymentMode`（`DEPOSIT/FULL`）是订单收款模式，与本次酒店字段无关，不得删除或改名。
+
+## 六、前端验收清单
+
+| # | 验收项 | 预期 |
+| --- | --- | --- |
+| 1 | 酒店资源编辑 | 可保存含早餐、可开发票、订房回复联系人 |
+| 2 | 选酒店弹窗 | 支付方式默认等于候选酒店 `settleType`，可改 |
+| 3 | 默认保存 | 配房详情回显修改后的 `settleType`，资源酒店不变 |
+| 4 | 显式同步 | `syncSettleType=true` 后资源酒店 `settleType` 同步变化 |
+| 5 | 现付文案 | 第 1 行为“领队前台现付，价格保密。” |
+| 6 | 签单文案 | 第 1 行为“签单，价格保密。” |
+| 7 | 公司付款文案 | 第 1 行为“公司付款，价格保密。” |
+| 8 | 电话回退 | 核房电话为空时显示联系人电话 |
+| 9 | 联系人回退 | 订房回复联系人为空时显示酒店联系人 |
+| 10 | 复制实现 | 复制内容与后端 `messageBody` 逐字一致，不重拼旧话术 |
+| 11 | 删除旧字段 | 酒店/房务页面不再引用 `paymentMode` |
+| 12 | 订单收款模式 | 订单主单 `paymentMode=DEPOSIT/FULL` 仍正常 |
+
+## 七、不影响范围
+
+- 现有报价、订单创建和价格固化仍继续使用协议价 `protocolPrice/protoPrice`。
+- 结算价 `settlementPrice` 的既有逻辑不变。
+- 本次不修改 `hl-ui` 代码；以上均为正式前端交接内容。