docs(changelog-v2): 站内信订单消息改按会话聚合+团号+跳转 前端对接spec(后端零改动复用/chat/conversations)

changelogs-v2/2026-06/25_站内信订单消息改按会话聚合+团号+跳转_前端对接_管理后台.md

@@ -0,0 +1,96 @@
+# 站内信「订单消息」改为按会话聚合 + 团号标题 + 跳转按钮（前端对接 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 注意
+
+1. `orderNo`/订单维度字段是软依赖 order-v3，测试环境用无真实订单的 bizId（如 88888）时为 null，属正常；真实订单会有团号。
+2. 跳转目标页路由以前端实际为准（本文路由摘自截图 Image #4 `/housekeeper/orders`、Image #5 `/order-v2/detail/{id}`）。
+3. 有疑问找后端（王骁/wx）对字段。