API Changelog Bot b661ff7e89 文档(order+user/admin): 房务「联系房务」面板真实化已上线可对接(#4223 PR#4247)

取代同日「需求澄清·实现中」版。已部署测试服+API验证:
- 订单详情 hotelRequirementBrief 加 claimerId(未抢单 null->前端「未知」)
- 聊天 open/open-house/conversations 加 peerOnline(真实在线态,SSE+Redis TTL near-live)
- 新端点 POST /admin/message/chat/open-house(HOUSE 订单维度单会话 HOUSE:{orderId})
- 抢单前发消息·抢单/转单后送达(后端自动);同人不自聊

2026-06-22 17:44:44 +08:00

5.5 KiB

原始文件 Blame 文件历史

房务「联系房务」面板真实化：真实在线态 + 抢单前发消息 + claimerId（已上线测试服·可对接）

变更类型：✅ 新增/修改接口（已部署测试服并 API 验证，可对接）端类型：管理后台（订单详情·定制师侧「联系房务」聊天面板）日期：2026-06-22 ｜工单：#4223 ｜ PR：#4247 ｜服务：hl-user-service（聊天/在线态）、hl-order-service-v3（订单详情/抢单）关联：本条取代同日「需求澄清·实现中」版（那版的"先别删在线态"结论已落地为下方真实契约）。

背景

此前「联系房务」面板的房务专员/在线态是前端假数据。wx 拍板：在线/离线要做成真的（不是删功能），并加「抢单前也能发消息、抢单后一并送达房务」。后端已补真实能力，本条是正式对接契约。

三态总览（前端按此渲染）

抢单状态	房务专员	在线态	发消息
抢单前（claimerId=null）	显示「未知」	不显示	可发，存订单房务会话，抢单后送达
抢单后（claimerId 有值）	真实接单人姓名	真实在线/离线（peerOnline）	正常聊
claimerId==当前登录人（你既定制师又抢了本单房务）	不显示「联系房务」	—	不能跟自己聊

1. 订单详情新增 `claimerId`

GET /v3/admin/order/{id}/itinerary 的住宿需求摘要 hotelRequirementBrief 新增 claimerId（接单房务 adminId，String 雪花；未抢单为 null）。

claimerId == null → 前端房务专员显示「未知」、不显示在线点、「联系房务」可引导但开的是 pending 会话（见 §3）。
claimerId == 当前登录 adminId → 前端隐藏/置灰「联系房务」（本单房务是你自己）。

2. 聊天出参新增 `peerOnline`（真实在线态）

POST /admin/message/chat/open、/open-house、GET /admin/message/chat/conversations 出参新增 peerOnline(Boolean)。

语义：对方（房务专员）当前登录后台且有活跃实时(SSE)连接 = 在线；离线靠 Redis TTL 反映（near-live，最多约 45s 延迟，本期不做在线态即时推送）。
前端：peerOnline==true 绿点在线 / false 灰点离线；抢单前（peer 为占位）恒 false、配合「未知」不显示状态即可。

3. 新端点 `POST /admin/message/chat/open-house`（HOUSE 会话订单维度）

HOUSE 房务会话改为订单维度单会话（键 HOUSE:{orderId}，一单一条；「联系房务」与「联系定制师」收敛到同一条，不再分叉）。FLEET/DIRECT 不变。

POST /admin/message/chat/open-house

字段	类型	必填	说明
orderId	String	✅	订单 id（房务会话维度）
peerAdminId	String	否	对端 adminId：抢单前定制师开聊不传（pending）；抢单后传 `claimerId`（定制师→房务）或 `consultantId`（房务→定制师）

出参（实测）：{conversationKey, peerAdminId, peerName, peerRole, peerOnline, unreadCount, isNew}。

抢单前不传 peerAdminId → 返 peerAdminId:0, peerName:null, peerRole:"HOUSE", peerOnline:false（占位「待接单房务」），定制师即可发消息（走现有 POST /chat/{conversationKey}/messages）。
peerAdminId==自己 → 281005（不能跟自己开会话）。

4. 抢单前发消息 · 抢单/转单后送达（后端自动，前端无需特殊处理）

抢单前定制师在 HOUSE:{orderId} 会话发的消息先暂存。
房务抢单后：后端自动把历史消息变成该房务的未读 + SSE im-chat 通知；定制师/房务双方此后正常聊。
转单：会话历史跟随交给新房务（前端拉 GET /chat/{conversationKey}/messages 即见全历史）。
边界（定制师==房务本人抢单）：消息仅作历史、不自发未读。
前端只需：抢单前用 open-house(pending) 让定制师能发；抢单后用 claimerId open-house 正常聊。送达逻辑后端全包。

5. curl 实测（2026-06-22 测试服，过网关 9443）

# A) 订单详情 claimerId
curl 'https://api.test.1814.love:9443/v3/admin/order/2068234602970828802/itinerary' -H 'Authorization: Bearer <token>'
#   → 200, hotelRequirementBrief.claimerId 字段存在（未抢单为 null）

# B) open-house（抢单前 pending）
curl -X POST 'https://api.test.1814.love:9443/admin/message/chat/open-house' \
  -H 'Authorization: Bearer <token>' -H 'Content-Type: application/json' -d '{"orderId":"2068234602970828802"}'
#   → 200 {"conversationKey":"HOUSE:2068234602970828802","peerAdminId":0,"peerName":null,
#          "peerRole":"HOUSE","peerOnline":false,"unreadCount":0,"isNew":true}

6. 前端处理建议

房务专员名：claimerId 空→「未知」；非空→真实姓名（姓名走会话 peerName）。
在线点：读 peerOnline（抢单后才有意义）；抢单前/未知不显示。
「联系房务」：claimerId==当前人→隐藏；否则 open-house（抢单前不传 peerAdminId、抢单后传 claimerId）。
「联系定制师」（房务侧）：改走 open-house（传 consultantId），与「联系房务」同一条订单会话。
删除写死的「舒心在线」假数据。

7. 影响 / 回滚

兼容性：均为加字段 / 加端点，旧前端不读新字段不受影响。
无 DB 迁移（复用 admin_message / admin_conversation_member）。回滚 = revert PR #4247 重新部署 hl-user-service + hl-order-service-v3。

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