diff --git a/changelogs-v2/2026-07/23_5180_订单详情联系车务独立未读红点-修改接口-管理后台.md b/changelogs-v2/2026-07/23_5180_订单详情联系车务独立未读红点-修改接口-管理后台.md new file mode 100644 index 0000000..51010af --- /dev/null +++ b/changelogs-v2/2026-07/23_5180_订单详情联系车务独立未读红点-修改接口-管理后台.md @@ -0,0 +1,93 @@ +# 订单详情「联系车务」独立未读红点 + +> 日期:2026-07-23 +> 工单:HL #5180 +> 影响范围:管理后台订单详情 → 行程安排 → 用车安排;聊天 SSE 实时状态 +> 状态:前端待处理 + +## 1. 问题与口径 + +车务通过 `FLEET:{orderId}` 会话给定制师发送消息后,顶部全局铃铛能显示未读,但当前订单「联系车务」按钮没有订单维度红点。房务按钮已有同款能力,本次车务必须复用相同的角标样式、实时刷新和已读清零交互。 + +房务与车务未读是两个独立业务会话,禁止继续共用一个字段: + +- `unreadMessageCount`:当前登录定制师在本订单 `HOUSE:{orderId}` 会话的未读数,只供「联系房务」使用。 +- `fleetUnreadMessageCount`:当前登录定制师在本订单 `FLEET:{orderId}` 会话的未读数,只供「联系车务」使用。 +- 顶部铃铛全局未读只能说明“存在未读”,不能作为当前订单按钮是否亮红点的判断依据。 + +## 2. 接口变更 + +```http +GET /v3/admin/order/{id}/itinerary +``` + +响应新增: + +```json +{ + "unreadMessageCount": 0, + "fleetUnreadMessageCount": 2, + "canContactFleet": true, + "contactFleetDisabledReason": null +} +``` + +| 字段 | 类型 | 说明 | +| --- | --- | --- | +| `unreadMessageCount` | Integer | HOUSE 订单会话未读;既有字段,语义不变 | +| `fleetUnreadMessageCount` | Integer | FLEET 订单会话未读;新增字段;无会话、未登录或软依赖降级时为 `0` | + +两个字段必须分别消费,不能用 `fleetUnreadMessageCount || unreadMessageCount` 一类兜底混用,否则房务消息会错误点亮车务按钮。 + +后端内部取数同时增加可选 `unreadScope`: + +- FLEET 不传或传 `TEAM`:保持车务看板既有团队共享未读口径。 +- FLEET 传 `PERSONAL`:按指定 `adminId` 返回车务发给该定制师的个人未读;订单详情的 `fleetUnreadMessageCount` 使用此口径。 +- HOUSE:仍按成员行个人未读统计,行为不变。 + +该字段属于 order-v3 → user-service 内部契约,管理后台无需直接传递。 + +## 3. 前端实现要求 + +### 3.1 按钮角标 + +`VehicleArrangeCard.vue` 的「联系车务」按钮按 `RoomArrangeCard.vue` 原样复用 `NBadge`: + +- `fleetUnreadMessageCount > 0` 时显示红色数字角标。 +- `max=99`,`0` 自动隐藏。 +- 按钮禁用时仍可保留未读提示,不能因为 `canContactFleet=false` 静默吞掉既有会话未读;是否允许重新开会话继续遵守后端门控。 +- 样式、偏移、尺寸与「联系房务」保持一致,不新增另一套红点 CSS。 + +`v3Adapter.js` 需把行程接口的 `fleetUnreadMessageCount` 映射为独立本地字段(建议 `itineraryFleetUnreadCount`),不要覆盖现有 `itineraryUnreadCount`。 + +### 3.2 SSE 实时刷新 + +订单详情现有 `lastChatSignal` 监听只匹配 `HOUSE:{orderId}`。需要同时支持: + +```text +HOUSE:{orderId} -> 刷新联系房务角标 +FLEET:{orderId} -> 刷新联系车务角标 +``` + +收到当前订单的 `FLEET:{orderId}` `im-chat` / `im-chat-read` 信令后,轻量重拉行程接口并只合并 `fleetUnreadMessageCount`;不能整页闪骨架屏,也不能把其他订单的全局未读数套到当前订单。 + +### 3.3 已读清零与竞态 + +- 打开「联系车务」并收到聊天抽屉 `read` 事件后,立即把当前订单车务角标本地清零。 +- 房务已读只清 HOUSE 字段,车务已读只清 FLEET 字段,互不影响。 +- 复用房务现有 `chatReadEpoch`(或等价版本号)防竞态:已读期间较早发出的刷新请求返回时,不得把旧未读数重新覆盖成红点。 +- 切换订单时按新 `orderId` 重算,不能沿用上一个订单角标。 + +## 4. 验收场景 + +- [ ] 当前订单无未读时,「联系车务」不显示角标。 +- [ ] 车务给本单定制师发送 1 条消息后,不刷新页面,顶部铃铛和本单「联系车务」都立即显示红点/数字 `1`。 +- [ ] 当前订单无车务未读、其他订单有车务未读时,顶部铃铛可亮,但当前订单「联系车务」不亮。 +- [ ] 当前订单只有房务未读时,只点亮「联系房务」,不得点亮「联系车务」。 +- [ ] 打开本单车务会话并读完后,「联系车务」角标立即消失,顶部铃铛与站内信列表同步收敛。 +- [ ] 已读操作与 SSE 刷新并发时,旧请求不会让已清零红点复现。 +- [ ] 角标样式、最大数字和按钮布局与房务模块一致。 + +## 5. 兼容性 + +新增响应字段为加性变更。未接入新字段的旧前端行为不变;前端接入后仍使用既有 `POST /admin/message/chat/open-fleet` 打开会话,`orderId` 必须使用数字雪花字符串,不能使用 `HL...` 展示号。