文档(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})
- 抢单前发消息·抢单/转单后送达(后端自动);同人不自聊

changelogs-v2/2026-06/22_4223_房务联系房务面板真实化-在线态+抢单前发消息+claimerId-上线测试服-管理后台.md

@@ -0,0 +1,72 @@
+# 房务「联系房务」面板真实化：真实在线态 + 抢单前发消息 + 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）
+```bash
+# 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。

changelogs-v2/2026-06/22_4223_订单详情联系房务在线态需求澄清-后端补真实在线态+claimerId-管理后台.md

@@ -1,38 +0,0 @@
-# 订单详情「联系房务」面板 在线态/房务专员 —— 需求澄清 + 后端补真实在线态 + claimerId（#4223）
-
-> 变更类型：📌 需求澄清 + 后端实现中（**作废 6-22 上一版「让前端去掉在线态」的结论**）
-> 端类型：管理后台（订单详情·定制师侧「行程安排 → 联系房务」聊天面板）
-> 日期：2026-06-22
-> 工单：#4223 ｜ 服务：hl-user-service（在线态/聊天）、hl-order-service-v3（订单详情）
-
----
-
-## ⚠️ 先读：上一版结论作废
-
-上一版 changelog 写「后端无在线态来源，请前端去掉在线/离线绿点」—— **这条作废，抱歉（后端误判产品意图）**。在线/离线**要保留并做成真的**，由后端补能力，不是删功能。
-
-## 产品规格（wx 拍板 2026-06-22）
-
-| 抢单状态 | 房务专员 | 在线态 |
-|---|---|---|
-| **抢单后** | 真实接单人姓名 | **真实在线 / 离线** |
-| **抢单前（无接单房务）** | **「未知」** | 不显示 |
-
-- 抢单前 `claimerId / claimerName` 为空 → 前端显示「未知」、不显示在线点。
-- 抢单后显示真实房务专员姓名 + 真实在线/离线状态。
-
-## 后端正在补（#4223）
-
-1. **真实在线态（presence）**：房务专员（admin）当前登录后台且有活跃实时（SSE）连接 = 在线；离线靠 TTL 反映（near-live，最多约 45s 延迟，本期不做在线态即时推送）。
-2. **聊天出参加 `peerOnline`**：`POST /admin/message/chat/open` 与 `GET /admin/message/chat/conversations` 出参新增 `peerOnline`(Boolean) → 驱动绿点。
-3. **订单详情补 `claimerId`**：行程住宿需求摘要（hotelRequirementBrief）加 `claimerId`（接单房务 adminId，前端开聊天用 `peerAdminId`；未抢单为 null）。
-
-## 前端动作
-
-- **在线态绿点：先别删**；待后端上线后接 `peerOnline`（抢单后真实态；抢单前不显示）。
-- **房务专员**：`claimerName`/`claimerId` 为空（未抢单）→ 显示「未知」、不显示在线点；有值 → 显示姓名 + 按 `peerOnline` 显示在线/离线。
-- **开聊天**：抢单后用订单详情的 `claimerId` 作 `peerAdminId` 调 `/chat/open`。
-
-## ⏳ 正式联调
-
-本节先给**方向**。完整字段 / 示例 / curl 以「**后端上线测试服并验证后的更新版 changelog**」为准，请勿据此提前联调（避免对未验证契约联调踩坑）。