5.5 KiB
5.5 KiB
站内信「订单消息」改为按会话聚合 + 团号标题 + 跳转按钮（前端对接 spec · 管理后台）
- 类型：前端改造对接说明（后端零改动，复用现成接口）
- 端类型：管理后台（hl-ui）
- 日期：2026-06-25
- 后端联系人：王骁（wx）
- 关联：站内信收件箱混排聊天（#4382 / #4386）的后续优化；INAPP-CHAT v1.0 §1.2 会话列表
⚠️ 本文是给前端（mmg）的对接 spec，不是后端变更。后端接口与字段全部现成，无需改后端。
1 背景 / 为什么改
#4382 把聊天混排进站内信「订单消息」是逐条消息模型，实测发现它注定数据不全：
- 站内信收件箱本质是「一条消息只在收件方名下存一行」，所以只显示你收到的那一半（你自己发的不进你自己收件箱）；
- 释放/转单会把整段对话归属转移，导致旧参与方收件箱里看不到。
结论：聊天应按会话展示，不是按单条消息。故站内信「订单消息」改为 一会话一行（像聊天软件的会话列表），点开看整段对话。
2 用现成接口（后端零改动）
2.1 会话列表接口
GET /admin/message/chat/conversations?bizModule=HOUSE&pageNo=1&pageSize=20
Authorization: Bearer {adminToken}
bizModule：HOUSE（配房会话）/FLEET（配车会话，车务接入后）；不传=当前员工全部会话。「订单消息」tab 取订单相关会话，可传HOUSE（车务上线后再并FLEET，或不传取全部业务会话）。- 分页：
pageNo/pageSize；按lastMessageAt倒序。 - 数据按收件人隔离（每人只看自己参与的会话），无需额外权限处理。
2.2 返回字段（ChatConversationRespVO，均已存在）
| 字段 | 类型 | 用途 |
|---|---|---|
orderNo |
String | 团号（订单号）→ 放标题。仅 HOUSE 会话有；order-v3 不可达/非 HOUSE 时为 null |
bizId |
Long | 订单ID → 跳转用（配房页/需求页都用它定位订单） |
bizModule |
String | HOUSE/FLEET，判跳配房页还是配车页 |
peerName |
String | 对方姓名（如「王骁」） |
peerRole |
String | 对方角色码 HOUSE/CUSTOMIZER/FLEET |
peerRoleLabel |
String | 对方角色中文（如「定制师」） |
peerOnline |
Boolean | 对方在线态（绿点） |
unreadCount |
Integer | 本会话未读数（红点） |
lastMessagePreview |
String | 最后一条消息预览（放副标题/内容列） |
lastMessageAt |
String | 最后活跃时间 |
customerName |
String | 订单联系人（如「王完善」），可拼进标题 |
destination/tripDays/bizStatusLabel/progressDesc |
— | 订单维度信息，按需展示 |
3 前端要做的事
3.1 标题加团号
每行标题 = 团号 orderNo（建议再拼客户名 customerName），例：HL20260624092836856 · 王完善。
orderNo为 null（无真实订单/order-v3 不可达）时降级显示对方名或会话键，不要显示空白。
3.2 行内信息
- 对方：
peerName+peerRoleLabel（+peerOnline绿点） - 预览：
lastMessagePreview - 未读红点：
unreadCount（>0 显示） - 时间：
lastMessageAt - 点击行 → 打开该会话线程（用
conversationKey调线程接口GET /admin/message/chat/messages，已有）
3.3 跳转按钮（按当前登录员工角色定目标页）
每行加一个「跳转到业务页」按钮，目标页 = 看当前登录员工是哪一侧（可由 peerRole 反推：peer 是定制师→我是房务/车务；peer 是房务/车务→我是定制师；也可直接用前端已知的当前用户角色）：
| 当前员工 | 会话 bizModule | 跳转目标 | 路由（按截图，前端核对实际路由） |
|---|---|---|---|
| 房务 | HOUSE | 配房页（房务管家配房） | /housekeeper/orders（带 bizId 定位/打开该订单配房详情，见截图 Image #4） |
| 车务 | FLEET | 配车页（车务管家派车） | 车务配车页（带 bizId，路由前端定） |
| 定制师 | HOUSE/FLEET | 需求页（定制师订单详情） | /order-v2/detail/{bizId}（行程安排→提交房型需求，见截图 Image #5） |
跳转只需
bizId（订单ID）+ 当前员工角色 +bizModule，这些前端都拿得到。后端不提供跳转 URL（避免后端耦合前端路由）。
4 tab 归属建议（前端 IA 自定）
- 订单消息 tab → 本会话列表接口（按会话聚合，团号+跳转）。
- 普通消息 tab → 系统通知：
GET /admin/message/list?messageType=NORMAL（仅系统通知，不含聊天）。 - 全部 tab → 由前端决定：可「会话列表 + 系统通知」两段合并展示，或仅系统通知。
- 顶部铃铛未读总数仍走
GET /admin/message/unread-count（含聊天+通知全部未读）。
说明：#4382/#4386 给
/admin/message/list做的「逐条混排聊天 + 派生标题」保留可用（如某处仍要平铺消息流），但「订单消息」tab 推荐改用本会话列表，体验更完整。
5 注意
orderNo/订单维度字段是软依赖 order-v3，测试环境用无真实订单的 bizId（如 88888）时为 null，属正常；真实订单会有团号。- 跳转目标页路由以前端实际为准（本文路由摘自截图 Image #4
/housekeeper/orders、Image #5/order-v2/detail/{id}）。 - 有疑问找后端（王骁/wx）对字段。