diff --git a/changelogs-v2/2026-06/27_4427_配房询房候选流程-询房中天级态+候选清单+单日确认同步协议价-管理后台.md b/changelogs-v2/2026-06/27_4427_配房询房候选流程-询房中天级态+候选清单+单日确认同步协议价-管理后台.md new file mode 100644 index 0000000..a1ba0c9 --- /dev/null +++ b/changelogs-v2/2026-06/27_4427_配房询房候选流程-询房中天级态+候选清单+单日确认同步协议价-管理后台.md @@ -0,0 +1,76 @@ +# 配房「先询房选候选 → 单日确认定一家」流程 — 详情逐日补询房中态/候选清单 + 单日确认同步协议价 + +> 变更类型:✨ 新增字段 + 接口接线说明(后端已就绪,**房务管家前端需按此接线**) +> 端类型:管理后台(房务管家·配房工作台) +> 日期:2026-06-26 | 工单:#4427 | PR:#4433 | 服务:hl-order-service-v3(双实例已部署 health UP,**测试服 API+DB 实测通过**) + +--- + +## 背景:房务配房两阶段流程 +1. **第一次选酒店/房型 = 选「询房候选」(可多家)** → 当天进入「询房中」 → 复制话术问酒店。 +2. **「单日确认」= 从候选挑一家定下来** → 当天配房完成(一天一家)。 + +后端能力本就齐:候选落 `house_inquiry_message`(一家一行);确认走询房回填转配房。本次补齐**详情把「询房中」显示出来 + 当天候选清单**,并让单日确认支持改结算价/同步协议价。 + +--- + +## 一、配房详情新增字段(`GET /admin/house/orders/{orderId}` → `itinerary[]`) + +### 1. 逐日状态 `arrange` 新增「询房中」 +`itinerary[].arrange` 取值由原 `pending`/`confirmed` 扩为三态,`arrangeLabel` 为中文: +- `pending` / **待配房**:当天无询房、无配房。 +- `waiting` / **询房中**(新):当天有进行中的询房(PENDING 待回复 / REPLIED 已回复)且尚未定稿配房。 +- `confirmed` / **已确认**:当天已有配房行(**优先级最高**——即便还有遗留询房,也显已确认)。 + +### 2. 逐日新增 `inquiries[]` 当天询房候选清单 +`itinerary[].inquiries`(数组,无询房则空数组)——供「单日确认」弹窗列候选选保留哪家。每项字段: + +| 字段 | 类型 | 说明 | +|------|------|------| +| `inquiryId` | String(雪花) | 询房记录 ID(回填/确认时用) | +| `hotelId` | String(雪花) | 酒店 ID | +| `hotelName` | String | 酒店名 | +| `roomCategory` | String | 房型类别字典 code(询房只到类别粒度;**具体房型 ID 由前端单日确认时从该酒店房型列表现选**,故候选不带 roomTypeId) | +| `roomCount` | Integer | 询问间数 | +| `status` | String | 询房状态:PENDING/REPLIED/CONFIRMED/REJECTED/TIMEOUT | +| `statusLabel` | String | 中文:待回复/已回复/已确认/已拒单/已超时 | +| `replyPrice` | String(金额) | 酒店回复报价(未回则空) | +| `replyAvailable` | Integer | 酒店回复可用房数(未回则空) | +| `priority` | String | NORMAL/URGENT | +| `timeoutAt` | DateTime | 询房超时刻(create + 4h) | + +> 已取消(CANCELLED)的询房不进清单。 + +--- + +## 二、前端接线(房务管家,mmg 需改) + +### 1. 第一次选房 → 走「发询房」(多候选),不要走「配房」 +- **第一次给某天选候选酒店/房型 → 逐个调 `POST /v3/admin/order/inquiry/send`**(一家一调,body 见下),不要调配房保存 `…/assignments`。 + - 原因:配房保存是「一天一家**定稿**」模型(按天归集,多家只留一家)——这就是「选多个酒店只存一个」的根因。多候选必须落询房表。 + - `send` body:`{requirementId, hotelId, dayNumber, stayDate, nights, roomCount, roomCategory, messageBody?}`;返回 `wechatTemplate`(话术,供复制)。 +- 复制话术:`POST /v3/admin/order/inquiry/preview`(所见即所发,不落库),或直接用 send 返回的 `wechatTemplate`。 +- 发起后该天 `arrange` 自动变 `waiting`/**询房中**,前端据此显示徽章。 + +### 2. 「单日确认」→ 弹窗列候选选一家 → 回填转配房 +- 弹窗数据源:详情 `itinerary[].inquiries`(或 `GET /v3/admin/order/inquiry?requirementId=&...` 历史)。 +- 选定一家 → `POST /v3/admin/order/inquiry/{inquiryId}/reply`,`convertToAssignment=true` → 落配房,该天变「已确认」。 +- **可在确认时改价**: + - 改结算价:传 `replyPrice`(→ 落配房成交售价 sellPrice)。 + - **同步到协议价(新)**:传 `syncProtocolPrice=true` —— 把本次结算价(replyPrice)同步写回 resource 协议价(**与配房 `syncProtocolPrice` 同口径**,无需另填值)。需同时传 `roomTypeId`(前端从该酒店房型列表带入,写回价格日历定位用)。 + - 也可走原显式路径:`syncToCalendar=true` + `newProtocolPrice`/`newStock`(显式另填协议价/库存)。 + +--- + +## 接口速查 +| 操作 | 接口 | +|------|------| +| 发起询房(一家一调,多候选) | `POST /v3/admin/order/inquiry/send` | +| 话术预览 | `POST /v3/admin/order/inquiry/preview` | +| 询房历史/候选 | `GET /v3/admin/order/inquiry?requirementId=` | +| 单日确认(选一家定稿,可改结算价/同步协议价) | `POST /v3/admin/order/inquiry/{inquiryId}/reply`(convertToAssignment=true,可带 replyPrice / syncProtocolPrice / roomTypeId) | +| 详情逐日态+候选清单 | `GET /admin/house/orders/{orderId}` → `itinerary[].arrange`(+waiting/询房中) / `itinerary[].inquiries[]` | + +## 测试服实测(已通过) +- 详情逐日 `inquiries[]` 正确归集当天候选:发一条询房 → DAY 候选清单回 `status=PENDING/待回复`、中文 statusLabel、报价/可用房/优先级齐全;该天有配房时 `arrange` 保持 `confirmed`(已确认优先)。 +- 全量单测 4668 通过(含三态 + 候选归集 + 同步协议价写回 replyPrice 当协议价 UT)。