API Changelog Bot 1f77becb70 docs: 通知前端接入酒店支付方式与询房话术

2026-07-10 18:27:10 +08:00

8.6 KiB

原始文件 Blame 文件历史

酒店支付方式快照与订房确认话术

状态：frontend-todo
后端工单：wx/HL#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

示例：

{
  "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 已删除，前端类型和兼容代码同步删除。

提交或替换配房

接口：

POST /v3/admin/order/hotel-requirements/{requirementId}/assignments

items[] 新增：

{
  "hotelId": "200001",
  "roomTypeId": "300001",
  "settleType": "cash",
  "syncSettleType": false
}

字段	类型	必填	约束	说明
`settleType`	String	否	`cash/sign/company`	不传时取酒店资源当前配置并冻结到快照
`syncSettleType`	Boolean	否	默认 `false`	`true` 才把本次支付方式写回酒店资源

修改单条配房

接口：

PUT /v3/admin/order/assignments/{assignmentId}

请求体同样支持：

{
  "settleType": "sign",
  "syncSettleType": true
}

交互要求：

PickHotelModal.vue 增加“支付方式”，默认带出候选酒店的 settleType，允许修改。
选中项必须保留 settleType，提交配房时透传，不能只保留价格字段。
与协议价、结算价一致，支付方式写回资源必须由用户显式确认；未确认传 false。
编辑已配房记录时，默认使用 assignments[].settleType；旧快照为空时可回退当前候选酒店的 settleType。
支付方式不做金额转换，也不要使用 Number()。

四、复制询房话术

接口：

POST /v3/admin/order/inquiry/preview

已配房场景请求

复制按钮当前只在“已配房/询房中”后可用，因此必须把订单和配房 ID 传给后端：

{
  "hotelId": "200001",
  "orderId": "30456",
  "assignmentId": "99999"
}

后端按以下优先级生成：

内容	优先级
团号	`order.teamNo` → `order.orderNo` → `待补充`
日期、房型、间数	配房快照 → 请求兜底字段
支付方式	配房 `settleType` 快照 → 酒店资源 `settleType` → `cash`
核房电话	`roomSharePhone` → `contactPhone` → `待补充`
回复联系人	`bookingReplyContacts` → `contactPerson` → `待补充`
备注	酒店标签用 `、` 连接；无标签为 `无`

未保存配房的兼容请求

只有确实拿不到 assignmentId 时，才使用以下兼容参数：

{
  "hotelId": "200001",
  "orderId": "30456",
  "stayDate": "2026-08-11",
  "roomCount": 2,
  "roomCategory": "DOUBLE_BED"
}

旧参数 nights、messageBody 不再参与新模板生成，前端应移除。

响应与精确文案

{
  "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"
  }
}

复制结果必须保持为：

呼籁旅行 - 订房确认书：
团号：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 代码；以上均为正式前端交接内容。

8.6 KiB 原始文件 Blame 文件历史 Unescape Escape