hl-api-changelog/changelogs-v2/2026-06/59_站内信打开会话合并为1接口_订单消息用conversationKey跳转_前端对接-管理后台.md

站内信「打开会话」合并为 1 个接口（元信息+订单卡+首屏消息+合并未读+标记已读）+ 订单消息跳转用 conversationKey

模块：管理后台 · 站内信聊天（打开对话 + 订单消息行跳转） 类型：后端合并优化（已合并 dev-v3 + 部署测试服 + API 实测闭环）+ 前端对接 日期：2026-06-30 关联：PR #4666（打开会话合并）、#4664（会话浮现 last_message_at）；取代 58_ 的"单独调 conversations 取订单卡" —— 订单卡现已直接在打开会话接口返回

一、打开会话：5 接口 → 1 接口（前端必改）

前端反馈"打开一个对话要调 5 个接口太多、已读不该有独立接口"。已合并优化：打开会话只调 1 个接口，且查询即已读。

唯一需要调的接口（按场景三选一，都返回同一个 ChatOpenFullRespVO）

场景	接口
定制师↔房务 订单会话	POST /admin/message/chat/open-house body {orderId, peerAdminId?}
组长↔房务 订单会话	POST /admin/message/chat/open-house-lead body {orderId, peerAdminId}
普通 1:1（非订单）	POST /admin/message/chat/open body {peerAdminId, bizModule, bizId}

这一个接口一次性返回打开会话所需全部数据，并已把本会话标记为已读（不必再调 /read）。

ChatOpenFullRespVO 返回结构

{
  "conversationKey": "HOUSE:2071784830965620737",
  "peerAdminId": 2021059720172838914,
  "peerName": "王骁",
  "peerRole": "CUSTOMIZER",
  "peerRoleLabel": "定制师",
  "peerOnline": true,
  "unreadCount": 0,                 // 本会话未读（打开即已读，恒 0）
  "isNew": false,
  "unreadTotal": 3,                 // 我的合并未读总数(NOTIFY+CHAT，标记本会话已读后的最新值)，刷顶部角标用
  "order": {                        // 订单卡：仅 HOUSE/HOUSE_LEAD 会话有；非订单会话/ order-v3 不可达为 null
    "orderNo": "HL20260630103610215",
    "customerName": "吕思远",
    "destination": "海拉尔",
    "tripDays": 3,
    "bizStatusLabel": "配房中",
    "progressDesc": "已配 2/4 间",
    "productName": "游牧的森林-短途版",
    "adultCount": 2,
    "childCount": 1,
    "requirementId": 70456
  },
  "thread": {                       // 首屏消息(最新一页 20 条；上滑更早历史走 GET messages)
    "conversationKey": "HOUSE:2071784830965620737",
    "hasMore": false,
    "nextCursor": null,
    "list": [
      { "messageId":"2071792080350236674","senderAdminId":"2021059720172838914","senderName":"王骁",
        "senderRole":"CUSTOMIZER","msgType":"TEXT","priority":"NORMAL","content":"77721",
        "isMine":false,"readByPeer":false,"sentAt":"2026-06-30 11:04:59" }
    ]
  }
}

优化后的完整交互（满足「≤2 普通接口 + 1 SSE」）

• 打开会话 → 1 个普通接口：POST …/open-house（拿到 元信息 + 订单卡 + 首屏消息 + 合并未读，且已标记已读）。
• 上滑加载更早历史 → GET /admin/message/chat/{conversationKey}/messages?beforeId={上次最小id}&pageSize=20（纯分页读，无副作用）。
• 发消息 → POST /admin/message/chat/{conversationKey}/messages。
• 实时收消息/未读/已读回执 → 1 个 SSE（既有 admin-notify）。

【前端必改】

1. 打开会话只调 open/open-house/open-house-lead 之一，用返回的 order 渲染订单信息条、thread 渲染消息、unreadTotal 刷顶部角标。
2. 删掉打开时的这些调用：原单独的 GET .../messages（首屏改用 open 返回的 thread）、POST .../read（打开即已读，unreadTotal 已是标记后的值）、GET .../conversations?bizId=（订单卡改用 open 返回的 order，取代 58_）、GET /admin/message/unread-count（用 open 返回的 unreadTotal）。
3. /read、/unread-count、conversations 接口仍保留（会话列表视图仍用 conversations），但打开会话流程不再需要它们。
4. messages(GET) 只在上滑加载更早历史时调（用 thread.nextCursor/最小 messageId 作 beforeId）。

二、订单消息行的「跳转按钮」用 conversationKey（前端处理）

收件箱「订单消息」行（kind=CHAT）跳转按钮消失了。后端数据一直都在，前端按字段渲染即可：

• 普通消息（NOTIFY）：用 link 跳对应页面（不变）。
• 订单消息（CHAT）：用该行的 conversationKey 跳转 = 打开会话（即调上面的 open-house，conversationKey 形如 HOUSE:{orderId}，orderId 也可取行内 bizId）。这正是它之前的跳转行为，切到 list?messageType=ORDER（57_）后行组件漏带了 conversationKey，补回即可。

备注

• 订单卡 order 仅 HOUSE/HOUSE_LEAD 订单会话有，非订单会话或 order-v3 暂不可达时为 null，前端隐藏订单信息条即可，不报错。
• 打开历史老会话时后端会顺手对齐该会话"最后活跃"，使其正常出现在会话列表（修复个别老会话在列表里看不到的问题，#4664）。