docs(changelog): 定制师侧联系房务聊天门控+去mock+对接真实房务(管理后台前端) — 后端契约已就绪实测

changelogs-v2/2026-06/23_定制师侧联系房务聊天门控+去mock+对接真实房务_管理后台前端.md

@@ -0,0 +1,105 @@
+# 定制师侧「联系房务」：聊天门控 + 去写死 mock + 对接真实房务（管理后台前端）
+
+> 变更类型：🐛 前端渲染/交互错误（**后端契约已全部就绪 + 实测验证**，前端去 mock + 加门控即可，无需后端改动）
+> 端：管理后台 **定制师侧**（订单详情 `order-v2/detail/{orderId}` → 行程安排 → 住宿安排 → 右上「联系房务」按钮）
+> 日期：2026-06-23
+> 实测订单：`HL20260620152849917`（吴昊，orderId=2068234602970828802，**仍在抢单池/未抢单**）
+
+---
+
+## 一、问题（wx 复评，已是第 N 次「还是没对」）
+
+订单 **还在抢单池、尚未被任何房务抢单**，但定制师侧点「联系房务」却弹出与 **「舒心 房务专员」** 的聊天面板，含历史消息（"确认单发我一下" / "这个可以安排，我去对接一下"）、在线状态、快捷语。
+
+**这是错的**：未抢单 = 没有任何房务被指派到这单 = **无人可联系**。当前面板里的房务名、消息、在线态全是假的。
+
+---
+
+## 二、根因（后端实测坐实：全是前端写死 mock，后端如实返「无房务」）
+
+实测两个权威接口（均过网关 9443 + 真 admin token）：
+
+`GET /admin/house/orders/{orderId}` →
+```
+claim.claimerId   = null
+claim.claimerName = null
+claim.claimedAt   = null
+claim.isMine      = false
+progress.houseStatus = PENDING_CLAIM   (待配房)
+```
+
+`GET /v3/admin/order/{orderId}/itinerary` →
+```
+hotelGroup.requirement.claimerId   = null
+hotelGroup.requirement.claimerName = null
+hotelGroup.requirement.status      = PENDING
+```
+
+→ 后端明确返回「这单还没房务」。所以前端那个 **「舒心 房务专员」、两条聊天记录、在线状态——100% 前端写死 mock**，和真实订单无关。
+
+---
+
+## 三、规则（wx 已定，全局，两端对称）
+
+> **抢单后才能聊天（聊天 = 留言）**。未抢单 = 无指派房务 = 不能联系、不能聊天、不显任何房务信息。
+
+- 定制师侧「联系房务」与房务侧「联系定制师」是**同一条会话的两端**，**同一门控**。
+- 房务侧规则见 changelog `22_4237`（第 1 项抢单前隐藏聊天入口、第 H 项留言空态）。本篇是其**定制师侧镜像**。
+
+---
+
+## 四、正确行为（前端逐项落地）
+
+### 1. 门控「联系房务」入口（核心）
+权威字段（**二选一，建议用定制师侧本来就拉的 itinerary**）：
+- `GET /v3/admin/order/{orderId}/itinerary` → `hotelGroup.requirement.claimerId`（`null` = 未抢单）
+- 或 `GET /admin/house/orders/{orderId}` → `claim.claimerId` / `progress.houseStatus`
+
+判定与表现：
+- **未抢单**（`claimerId == null` 或 `houseStatus == PENDING_CLAIM`）：
+  - 「联系房务」按钮 **置灰/禁用**（或隐藏），hover/点击提示 **「订单在抢单池，待房务抢单后可联系」**。
+  - **绝不弹聊天面板、绝不显任何房务名/头像/消息/在线态**。
+- **已抢单**（`claimerId` 非空）：「联系房务」可用，进入第 2、3 步。
+
+### 2. 去 mock，对端显「真实抢单房务」
+抢单后聊天面板对端 = 真实房务，全部取后端：
+- 房务名 = `claimerName`（**删掉写死的"舒心"**）。
+- 对端 adminId = `claimerId`（开会话的 peer，见第 3 步）。
+- 历史消息 / 在线态 / 未读数 = 走真实站内信聊天接口，**删掉所有写死假消息、假在线、假未读**。
+
+### 3. 聊天通道契约（**抢单后才调**，与房务侧同一条会话，双向互通）
+开/找回会话：`POST /admin/message/chat/open`
+```json
+{ "bizModule": "HOUSE", "bizId": <orderId>, "peerAdminId": <claimerId> }
+```
+- `bizModule` 固定 `HOUSE`；`bizId` = 订单 id；`peerAdminId` **必传**（@NotNull）= 真实房务 `claimerId`。**没有 claimer 时根本不该调此接口**（无合法 peer）。
+- bizModule=HOUSE + bizId=orderId **唯一确定一条会话**，定制师侧与房务侧消息**互通**。
+- 发消息 / 拉历史 / 未读 / SSE 实时 走站内信聊天既有接口（与房务侧同一套，§chat 系列），此处不重复。
+
+### 4. 快捷语
+快捷语（客户想升级房型 / 能否换同档酒店 / 加一间房 / 调整入住日期 / 确认单发我一下）**保留**，但受同一门控——未抢单时入口都没有，自然发不出。
+
+---
+
+## 五、去 mock 自检清单（前端逐条清理）
+
+- [ ] 「舒心 房务专员」名称/头像 → 改 `claimerName`/真实头像；**未抢单不显**
+- [ ] 写死的聊天记录（"确认单发我一下" / "这个可以安排，我去对接一下"）→ **删**，改真实历史接口
+- [ ] 写死的「在线」状态 → 改真实在线态（拿不到则不显）
+- [ ] 「联系房务」按钮无条件可点 → 加 `claimerId` 门控（未抢单置灰 + 提示）
+- [ ] 未抢单仍弹聊天面板 → 改为引导文案，**不弹**
+
+---
+
+## 六、验收
+
+| 场景 | 期望 |
+|---|---|
+| 未抢单订单（本单 HL20260620152849917） | 「联系房务」**置灰 + 提示**；点不出聊天；**零房务名/零消息/零在线态** |
+| 已抢单订单 | 「联系房务」可用；对端 = **真实抢单房务**（claimerName）；消息全走真实接口 |
+
+---
+
+## 七、备注：后端硬门控（可选，待 wx 拍，默认先不做）
+
+当前 `POST /admin/message/chat/open` **未在后端校验** bizModule=HOUSE 时 `peerAdminId` 是否为该订单真实 claimer（现以前端门控为主）。若要后端兜底（防绕过 / 防错 peer），需 user-service 的 chat-open 增一次对 order-v3 的 claim 校验（跨服务 Feign）——属独立后端工单，**此前 #4237 已 flag，默认先不做**，需要再起单。