docs: 车务聊天定制师端已读回执修复 changelog (#5797/PR #5799)

changelogs-v2/2026-08/10_5797_车务聊天定制师端已读回执修复-修复-管理后台.md

@@ -0,0 +1,78 @@
+---
+schema: "hl-changelog/v2"
+ticket: "5797"
+title: "车务聊天定制师端气泡永远「已送达」修复——车务读过即显示「已读」，并新增定制师端点对点 READ 信令"
+consumer: "admin"
+author: "wx(GIT)"
+change_type: "修复"
+backend_status: "deployed"
+gateway_status: "not_required"
+frontend_status: "not_required"
+frontend_owner: "mmg"
+frontend_ref: ""
+target_release: ""
+verified_at: "2026-08-10"
+status_note: "接口契约零变化，前端无需改动即生效（readByPeer 字段在车务会话首次真正有值）。附带新增：车务团队读后向定制师推点对点 im-chat-read 信令，SSE 角标实时化接线时可顺带消费实现气泡实时翻「已读」。测试服 16:00 后已用真实 API + Redis 信令抓包验证通过。"
+updated_at: "2026-08-10"
+base: "dev-v3"
+generated: "2026-08-10T16:20:00+08:00"
+---
+
+# 车务/聊天: 定制师端气泡永远「已送达」修复——车务读过即显示「已读」
+
+> **服务**: hl-user-service
+> **PR**: #5799
+> **Issue**: #5797
+> **日期**: 2026-08-10
+> **影响范围**: 管理后台车务订单聊天（FLEET:{orderId} 会话）定制师端气泡已读态；聊天 READ 信令
+
+---
+
+## 一、背景
+
+定制师在订单详情聊天框给车务发消息后，无论车务/超管是否已打开聊天窗读过，定制师端气泡**永远显示「已送达」**、刷新也不变「已读」。服务端团队共享已读水位其实一直在正常推进（#5792 修复后车务侧红点清零正常），坏的只是定制师端「读出来」这半边——#4689 车务聊天上线起即存在。
+
+## 二、根因（后端，接口契约无关）
+
+车务团队占位 adminId=0 与房务「抢单前无人接单」占位 0 **撞值**：定制师成员行的对端恒为 0（=车务团队），后端解析对端已读水位时把 0 一律当房务占位短路返 null → `readByPeer` 恒 false。
+
+## 三、变更（均后端内部，接口路径/请求/响应结构零变化）
+
+| # | 变化 |
+|---|---|
+| 1 | 对端=车务团队时改读 admin_id=0 团队行共享水位 → **任一车务/获准超管读过，定制师端 `readByPeer` 即为 true**（open / open-fleet / 消息分页单一漏斗全覆盖）；房务抢单前占位行为不变 |
+| 2 | **新增**：车务团队读且水位实际推进时，向当前定制师推一条**点对点 `im-chat-read` 信令**（payload：`adminId`=定制师、`readerAdminId`、`lastReadMessageId`、`conversationKey`；此前定制师收不到任何 READ——团队清零信令只按 VEHICLE_MANAGER 角色广播） |
+| 3 | 读侧对齐发送侧「定制师身份优先」：定制师本人持超管角色打开自己会话时，推进自己行而非团队水位（否则自读会把自己气泡刷成「已读」） |
+
+## 四、对前端的影响
+
+- **无需改动即生效**：刷新/重开聊天框后，`readByPeer` 在车务会话首次真正有值，气泡按现有渲染逻辑显示「已读」。
+- **给 SSE 角标实时化接线的顺带增强**（见关联 changelog）：定制师端现在会收到点对点 `im-chat-read` 信令，接入 chatSignalBus 后可把「自己发的、id<=lastReadMessageId」的气泡实时翻成「已读」，不必等刷新。信令结构与既有 #4289 点对点 READ 完全一致，无新字段。
+
+## 五、验证证据（2026-08-10 测试服）
+
+| 验证点 | 实测 |
+|---|---|
+| 定制师视角发消息、车务未读 | `readByPeer=false`（不误报） |
+| 车务读后定制师拉线程 | **`readByPeer=true`**（此前恒 false） |
+| 真实车务团队读（open-fleet） | 团队行水位 673→714、unread 1→0 |
+| READ 信令 Redis 抓包 | 两条：团队广播（targetRole=VEHICLE_MANAGER）+ **点对点（adminId=定制师）**，水位正确 |
+| 定制师本人（超管）自读 | 团队行水位不动（不再自己读自己） |
+
+- 单测：新增 11 例，chat 相关 219+33 全绿。
+- 现场顺带修复：订单 26-9313 定制师端三条「已送达」消息，部署后刷新即显示「已读」。
+
+## 关联 / 联系人
+
+### 链接
+
+- **Issue**: [#5797](https://git.1814.love:8443/wx/HL/issues/5797)
+- **PR**: [#5799](https://git.1814.love:8443/wx/HL/pulls/5799)
+- **Merge commit**: [31ffa7459](https://git.1814.love:8443/wx/HL/commit/31ffa7459)
+- **相关 changelog**: `changelogs-v2/2026-08/10_frontend_车务看板聊天角标实时化与已读联动-前端优化-管理后台.md`（SSE 接线时消费本单新增的点对点 READ 信令）
+- **前置修复**: #5792（车务读→团队红点清零半边）
+
+### 联系人
+
+- **后端负责人**: @wx
+- **前端负责人**: @mmg