docs(changelog): 联系房务契约裁决 — 作废误写的23_(基于stale代码), 22_4223补裁决答前端3问(open-house live/抢单前可发/在线态轮询/FLEET deferred)
这个提交包含在：
API Changelog Bot
父节点
a63cadb822
当前提交
a5c7d90b8d
@ -70,3 +70,22 @@ curl -X POST 'https://api.test.1814.love:9443/admin/message/chat/open-house' \
|
|||||||
## 7. 影响 / 回滚
|
## 7. 影响 / 回滚
|
||||||
- 兼容性：均为加字段 / 加端点，旧前端不读新字段不受影响。
|
- 兼容性：均为加字段 / 加端点，旧前端不读新字段不受影响。
|
||||||
- **无 DB 迁移**（复用 admin_message / admin_conversation_member）。回滚 = revert PR #4247 重新部署 hl-user-service + hl-order-service-v3。
|
- **无 DB 迁移**（复用 admin_message / admin_conversation_member）。回滚 = revert PR #4247 重新部署 hl-user-service + hl-order-service-v3。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 8. 补充裁决（2026-06-23 · 复核 + 答前端阻塞，本篇为唯一权威）
|
||||||
|
|
||||||
|
前端反馈本篇与同日另一篇 `23_定制师侧联系房务…管理后台前端.md` 契约打架（两个 open 端点 + 抢单前/后语义相反），无法切共享聊天基础设施。重新实测测试服后裁决：
|
||||||
|
|
||||||
|
**① 以本篇（22_4223 / open-house）为唯一权威。** 同日那篇 `23_…` **作废已删**——它基于**落后 90 个提交的 stale 代码**误写（写成 `POST /chat/open` + `bizModule/peerAdminId` + 「抢单后才能聊」），与真实部署不符。
|
||||||
|
|
||||||
|
**② 端点（实测 live，2026-06-23 过网关 9443）**：
|
||||||
|
`POST /admin/message/chat/open-house {"orderId":"…"}` → `200 {"conversationKey":"HOUSE:{orderId}","peerAdminId":0,"peerName":null,"peerRole":"HOUSE","peerOnline":false,"unreadCount":0,"isNew":…}`。
|
||||||
|
HOUSE 订单会话**只走 open-house**。通用 `/chat/open`（bizModule+peerAdminId，@NotNull）仍在，但用于 FLEET/DIRECT/显式 peer，**HOUSE 别用它**。
|
||||||
|
|
||||||
|
**③ 门控（更正「抢单后才能聊」的误解）**：定制师侧「联系房务」**抢单前也能发消息**——open-house 不传 peerAdminId → pending 占位「待接单房务」，消息暂存，房务抢单后后端自动送达。所以**抢单前按钮照常可点可发**，只是对端显「未知/待接单房务」、不显在线点；**不要禁用按钮**。仅 `claimerId == 当前登录人` 时隐藏（自己别跟自己聊）。
|
||||||
|
（注：与房务侧「房务管家」未抢单隐藏入口不冲突——房务在抢单池里没理由先聊；能抢单前留言的是**定制师**单向投递。）
|
||||||
|
|
||||||
|
**④ 在线态怎么拿（答「轮询还是 SSE」）**：读响应里的 `peerOnline`(Boolean)（open-house / conversations 都返）。它是**真实在线态**（后端 `adminPresenceService` Redis presence，对方有活跃后台连接=在线），**near-live、约 45s TTL 延迟**。刷新方式 = **轮询 / 重新拉**（re-open-house 或 re-conversations）。**没有专用在线态 SSE 推送**（本期不做）。消息实时到达走站内信 `im-chat` SSE（与在线态是两回事）。抢单前 peer 占位恒 `false`，配「未知」不显在线点即可。
|
||||||
|
|
||||||
|
**⑤ FLEET 车务聊天：未切真（deferred）。** 代码实证 `ConversationMemberService` 注「fleet 接入 deferred」——FLEET 会话的订单摘要 / 真实对端整合**没做**。通用 `/chat/open` 虽接受 `bizModule=FLEET`，但**无真实车务数据对接**。**前端 FLEET 聊天先别做切真**，等车务接入工单（wx「车务用了再加」）。mock 里没有 SSE/在线态属正常——FLEET 整条都还没切真。
|
||||||
|
|||||||
@ -1,105 +0,0 @@
|
|||||||
# 定制师侧「联系房务」：聊天门控 + 去写死 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，默认先不做**，需要再起单。
|
|
||||||
正在加载...
x
在新工单中引用
屏蔽一个用户