# 站内信「订单消息」改为按会话聚合 + 团号标题 + 跳转按钮（前端对接 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 跳转按钮（按**当前登录员工角色**定目标页 —— wx 已确认）
每行加一个「跳转到业务页」按钮，目标页 = **当前登录员工自己的角色**（前端已知当前用户角色，**直接用，不用 peerRole 反推**）：

| 当前员工 | 会话 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）对字段。