docs(changelog): 车务订单聊天(定制师↔车务团队,FLEET:{orderId})新接口 open-fleet + 车管控制台接入(#4689/PR#4690)

changelogs-v2/2026-07/02_4689_车务订单聊天_定制师车务团队_新接口_管理后台.md

@@ -0,0 +1,41 @@
+# 车务订单聊天(定制师 ↔ 车务团队,基于订单)——新增 open-fleet 接口 + 车管控制台接入
+
+> 模块：管理后台 · 车管控制台 · 订单聊天
+> 类型：**后端新增(已合并 dev-v3 + 部署测试服 + API 实测)** + 前端接入
+> 日期：2026-07-01 · 关联 PR #4690 / 工单 #4689
+> 说明：车务聊天是**房务订单聊天的团队化镜像**——会话键 `FLEET:{orderId}`,与房务 `HOUSE:{orderId}` 同构,大部分聊天接口**复用**。
+
+## 模型
+- 会话键 `FLEET:{orderId}`(一个订单一个车务会话)。
+- 两端：该订单**定制师** ↔ **车务团队**(多车务、无抢单、任一车务可参与任一订单);**双向**发起。
+- 未读=**团队共享**:定制师发消息→全体车务在该单亮红点;**任一车务读→红点对全体车务清零**;车务之间的回复不计入红点(只数定制师发的)。
+
+## 【前端 · 车管控制台】
+
+### 1. 打开车务订单会话(核心新接口)
+`POST /admin/message/chat/open-fleet`
+body:`{"orderId": 2071784830965620737}`(必填;可选 `peer`)
+返回 `ChatOpenFullRespVO`(与房务 open-house 同结构):`conversationKey`(=`FLEET:{orderId}`)、`isNew`、`peerName`/`peerRole`、`order`(订单卡:orderNo/customerName/productName/…)、`thread`(首屏消息,最新一页)、`unreadCount`/`unreadTotal`;**打开即标记已读**。
+- 车务点「联系定制师」→ 用它开会话(peer 自动=该单定制师)。
+- 定制师点「联系车务」→ 也用它(peer=车务团队)。
+
+### 2. 复用的通用聊天接口(与房务同,FLEET 会话直接用)
+- 发消息:`POST /admin/message/chat/{conversationKey}/messages` body `{"content":"..."}`
+- 拉历史(上滑分页):`GET /admin/message/chat/{conversationKey}/messages?pageSize=20&beforeId=...`
+- 标记已读:`POST /admin/message/chat/{conversationKey}/read`(open-fleet 已自动标已读,一般无需单独调)
+- 会话列表(定制师侧看到 FLEET 会话):`GET /admin/message/chat/conversations`
+- `conversationKey` 即 `FLEET:{orderId}`,路径里带冒号原样传(已实测可用)。
+
+### 3. 消息角色徽章
+- 车务回复:`senderRole=FLEET`。
+- **定制师广播:`senderRole=null`**(团队会话无单一收件人的历史设计)。前端在 FLEET 会话内**按「非 FLEET 即定制师」渲染徽章**(有 `senderName` 可显示姓名)。
+
+## 【订单列表红点——需后端订单列表接口配合(待定)】
+车务侧「订单列表行内红点」的数据源是 `biz-unread-batch`(bizModule=FLEET,团队共享未读),但它是**服务间 internal 接口(Feign 直连、不经网关,前端不能直接调)**。
+- 需要**车管控制台订单列表所走的那个后端列表接口**像房务 `grab-pool` 一样,内部调 `biz-unread-batch(bizModule=FLEET)` 把每单未读塞进列表项(字段如 `unreadMessageCount`)。
+- ⚠️ **待确认**:车管控制台的订单列表走哪个后端接口(order-v3 用车需求列表 / fleet-service 派单列表)?确定后由后端补这段 FLEET 未读透传(小改)。本次 PR 只交付了聊天本体 + 未读机制,列表透传是下一步。
+
+## 已验证
+- open-fleet 实测:200 + 订单卡(HL20260630103610215·吕思远·游牧的森林-短途版)+ 会话三行(车务→定制师 / 定制师→团队 / admin_id=0 团队共享水位行)。
+- 车务发消息→定制师收到(unread+1);车务读→团队共享水位推进(任一车务读全体清零)。
+- 单测 user-service 3099 绿(房务基线零回归)。