diff --git a/changelogs-v2/2026-07/55_4893_酒店支付方式快照与订房确认话术-前端待处理-管理后台.md b/changelogs-v2/2026-07/55_4893_酒店支付方式快照与订房确认话术-前端待处理-管理后台.md new file mode 100644 index 0000000..d4a496e --- /dev/null +++ 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` 代码;以上均为正式前端交接内容。