diff --git a/changelogs-v2/2026-06/25_站内信订单消息改按会话聚合+团号+跳转_前端对接_管理后台.md b/changelogs-v2/2026-06/25_站内信订单消息改按会话聚合+团号+跳转_前端对接_管理后台.md new file mode 100644 index 0000000..9b5a3ef --- /dev/null +++ b/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)对字段。