API Changelog Bot bfa877f3db docs(chat): 在线/离线实时SSE已上线(22_4223 §12, presence事件, #4273 PR#4299)

2026-06-23 15:43:42 +08:00

18 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。

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 整条都还没切真。

9. 切真细节契约（2026-06-23 实测 origin/dev-v3 + LIVE，答前端 Q1/Q2/Q3）

Q1 · peerAdminId 强不强制？后端解析对端吗？

HOUSE 用 POST /admin/message/chat/open-house，peerAdminId 选填（不传 = 抢单前 pending 占位「待接单房务」）。别用通用 /chat/open（它 peerAdminId @NotNull 强制，只给 FLEET/DIRECT/显式 peer）。
后端不反查 order-v3 解析对端（ChatManager.openHouse javadoc 明示「前端传 peer，不反查 order-v3」）。对端 id 前端传，且前端数据里都有：
- 定制师→房务：peerAdminId = claimerId（来自 hotelRequirementBrief.claimerId；抢单前为 null → 不传 = pending）。
- 房务→定制师：peerAdminId = consultantId（订单/抢单数据里就有）。
「两端收敛同一条会话」靠键 HOUSE:{orderId}（与 peer 无关）；但建双方成员行需开方各自传对端 id（抢单前定制师不传 → 房务抢单后 order-v3 afterCommit 自动补房务成员行 + 送达历史，前端无需管）。
FLEET：无 open-fleet，通用 open 强制 peerAdminId，且 FLEET deferred → 先别做。
可选增强：若要前端只传 orderId、后端按 claim/consultant 自动解析对端 → 需后端加 Feign 反查 order-v3，独立工单待 wx 定（当前不做，前端传 id 即可跑通）。

Q2 · 响应字段（实测对齐 #4020，别凭注释）

线程 GET /admin/message/chat/{conversationKey}/messages → {conversationKey, hasMore, nextCursor, list[]}。是 list 不是 records；list 按时间正序（旧→新，从上往下渲染）；游标 nextCursor = 本页最小 messageId，作下次 beforeId 上翻历史。
消息项 list[]：{messageId, senderAdminId, senderName, senderRole, msgType(TEXT/IMAGE/SYSTEM), priority(NORMAL/URGENT), content, isMine, sentAt}。
- isMine = Boolean，后端按 senderAdminId == 当前登录人 算（左右气泡布局用）。
- sentAt = String，格式 yyyy-MM-dd HH:mm:ss（如 2026-06-16 11:02:31）——不是毫秒、不是 ISO-8601，本地时间到秒、无时区无毫秒。前端按此格式 parse，别当 epoch/ISO。

Q3 · SSE 实时（已有且 LIVE，别再轮询）

SSE 端点 GET /ws/admin-msg/stream（text/event-stream）实测 LIVE（200 + 正确 Content-Type）。
发消息：后端 send 事务 afterCommit 经 Redis Pub/Sub 广播 CHAT 信令给收件方 → SSE 实时冒泡（带 senderName / 预览 / priority + conversationKey）。
前端应订阅 /ws/admin-msg/stream，收到 CHAT 信令即 live-append / 刷新对应会话，替换「发送后短轮询 6 次(~8s)」的兜底。「没有 SSE」= 没接，不是没有。

在线/离线态走 SSE（wx 2026-06-23 新要求 → 后端工单 #4273）

现状：peerOnline 是轮询字段（Redis presence key TTL 45s + SSE 心跳续期），在线态变更不推送。
wx 拍：改为 SSE 实时推在线/离线。已立后端工单 #4273（hl-user-service）：SSE 连接建/断 → 标在线/离线 → 向会话对端推 presence 事件。前端届时订阅 presence 事件、停 peerOnline 轮询（保留字段做首屏兜底）。✅ 已上线测试服，契约见 §12。

12. ✅ 在线/离线实时 SSE 已上线测试服（2026-06-23 · #4273 · PR #4299 · 已部署实测）

peerOnline 轮询升级为 SSE 实时推。前端订阅后在线点变更实时刷新，停掉 peerOnline 轮询（peerOnline 仅留作首屏兜底）。

SSE 事件：presence（与 im-chat/im-chat-read 同一条流 GET /ws/admin-msg/stream，实测 200 text/event-stream）。
payload：{ "type":"PRESENCE", "presenceAdminId":<Long 在线态翻转的人>, "online":<Boolean> }（另带 adminId=收件方路由，前端忽略）。
语义：当与你有活跃会话的某对端（presenceAdminId）上线/下线，你的流就收到一条 presence → 把会话列表 / 打开的聊天里那个人的在线点实时刷成 online。只推「与你有会话关系的人」，不会广播无关员工。
前端：订阅 presence 事件 → presenceAdminId 找到对应会话/对端 → 设其在线点=online。首屏仍用 peerOnline（open-house / conversations 返）兜底，之后全靠 presence 事件维持，不再轮询。
时延：上线≈即时（建连即推）；下线干净断开≈即时、异常掉线≤25s（心跳探测补推）、45s TTL 兜底。
实测：部署后 GET /ws/admin-msg/stream 200 + text/event-stream，服务正常启动（新 presence 广播 bean 无循环依赖）。两端实时翻态属前端联调验。

10.「已读」是前端写死的 bug + 抢单前应显「留言」（2026-06-23 wx 评审，🐛 前端改，后端无需动）

现象（wx 评审，定制师侧「联系房务」面板）：订单还在抢单池（无房务接单，对端显「待接单房务」），定制师发「你好测试消息」，气泡下却显示 14:05 **已读**。没有任何房务接单、对端是占位 0，谁来读？「已读」是错的。

根因（已对 origin/dev-v3 核实）：后端从不返回任何「已读/送达」状态。线程消息 VO 就 §9 Q2 那 9 个字段 {messageId, senderAdminId, senderName, senderRole, msgType, priority, content, isMine, sentAt}——没有 isRead/readAt/delivered/status。14:05 已读是前端在「我方」(isMine=true) 气泡下无条件硬拼的，后端给不了这个信号，所以它永远是假的。

正确显示（前端按 claim 状态自行渲染，后端已有的字段够用）：

我方消息所处状态	判据（前端已有）	气泡下应显示
抢单前（pending）	`claimerId == null`（或 open-house 返 `peerAdminId:0`/`peerName:null`）	「留言」或「留言·待房务接单」——不显已读
抢单后	`claimerId` 有值、对端真实	「已送达」或什么都不显——不显「已读」
对端发来的（`isMine=false`）	—	不需要已读标

一句话：把写死的「已读」删掉。抢单前我方消息本质是留言（标「留言」）；抢单后后端保证已送达接单房务（可标「已送达」）。后端无读回执，别再伪造「已读」。

「留言→抢单后送达」后端全包，无需前端管（§4 重申 + 核实）：

抢单前定制师发的消息 → 后端存进 pending 桶（收件方=占位 0，不累加任何人未读、不推 SSE），就是「留言」。
房务抢单那一刻 → 后端 bindHouseClaimer 自动把这些 pending 留言整批改判给抢到的房务 + 置未读 + SSE 通知。这就是你说的「发的消息抢单后一起把消息发过去」，已经实现。
所以你测试时「房务管家侧看不到留言」(Image #27) 是对的——那单还在抢单池、没人抢，留言正确地还压在 pending、尚未送达；等真有房务点「抢这一单」，留言会连同未读角标一起送到 ta 那边。

房务管家侧（Image #27）抢单池显「抢单后可与定制师沟通」= 设计内门控（见 22_4237 item 1：房务未抢单时隐藏聊天入口）。保持不变，与上面定制师侧抢单前能留言不冲突——能抢单前单向留言的只有定制师；房务在抢单池里没接单、无身份，自然先不聊。抢单后双方正常互聊。

两件待 wx 拍的「可选增强」（前端不必等，先按上表修假已读）：

真·已读回执（抢单后对方真读了才显「已读」）——需后端把 per-message 已读态（基于会话成员 lastReadMessageId 水位）暴露进线程 VO，是独立后端工单。当前最小修 = 前端按上表把假已读改成「留言/已送达」即可。
抢单池给房务「该单有 N 条定制师留言」预览做诱饵——需后端在抢单池 VO 补 pending 留言计数，独立后端工单。当前抢单后才送达可见。

11. ✅ 真已读回执 + 房务侧留言可见已上线测试服（2026-06-23 · #4288/#4289 · PR #4294 · 已 API 实测）

§10 标的两项 wx 已拍并实现上线，取代 §10 的「待定/显已送达」口径：

11.1 真实「已读/未读」回执（#4289）

线程消息出参（GET /admin/message/chat/{conversationKey}/messages 的 list[]）新增 readByPeer(Boolean)：仅我方消息(isMine=true)有意义 = 对端已读到本条（对端成员已读水位 >= 本消息 id）。抢单前无对端恒 false；对端发来的消息(isMine=false)此字段无意义。
气泡显示口径（升级版，取代 §10）：

我方消息状态气泡下显示

抢单前「留言」

抢单后 · readByPeer=false 「已送达」

抢单后 · readByPeer=true 「已读」

对端发来的(isMine=false) 不标
实时刷已读：对端调 POST /admin/message/chat/{conversationKey}/read 后，后端经 SSE 推 im-chat-read 事件给我方（payload {conversationKey, readerAdminId, lastReadMessageId}）→ 前端把本会话 id <= lastReadMessageId 的我方气泡刷「已读」。订阅 im-chat-read（与 im-chat 同一条 SSE 流 /ws/admin-msg/stream；NOTIFY/CHAT 事件不变向后兼容）。
实测：线程出参已含 readByPeer（字段顺序 …, isMine, readByPeer, sentAt）。

我方消息状态	气泡下显示
抢单前	「留言」
抢单后 · `readByPeer=false`	「已送达」
抢单后 · `readByPeer=true`	「已读」
对端发来的(`isMine=false`)	不标

11.2 房务侧「内部留言框」显示抢单前留言（#4288）

详见 22_4237：房务订单详情 GET /admin/house/orders/{orderId} 新增 messages 列表 + tabCounts.messageCount = 1(定制师需求) + N(留言)。抢单池/未抢单也返（房务在池里浏览即见定制师留言）。
实测（订单 2068234602970828802，抢单池态）：tabCounts.messageCount=3、messages=[「你好测试消息」2026-06-23 14:05、「确认单发我一下」14:32]。
messages[].senderRole 抢单前留言可能为 null（抢单前留言恒来自定制师，前端按「定制师」渲染即可）；senderName 已是真实姓名。

18 KiB 原始文件 永久链接 Blame 文件历史 Unescape Escape