608 行
26 KiB
Markdown
608 行
26 KiB
Markdown
---
|
||
schema: "hl-changelog/v2"
|
||
ticket: "7211"
|
||
title: "定制师 ↔ 团期管理员站内会话（GROUP:{orderId}）"
|
||
consumer: "admin"
|
||
author: "wx(GIT)"
|
||
change_type: "新增接口"
|
||
backend_status: "deployed"
|
||
gateway_status: "verified"
|
||
frontend_status: "verified"
|
||
frontend_owner: "mmg"
|
||
frontend_ref: "86340b24"
|
||
target_release: ""
|
||
verified_at: "2026-09-08"
|
||
status_note: "前端已交付并验证(commit 86340b24):chat.js 新增 openGroupChat(POST /message/chat/open-group,body 仅 {orderId} 字符串不传 peerAdminId,silentError),send 静默正则扩 /^(?:FLEET|GROUP):[^:]+$/、messages/read 对 GROUP 键静默,281002 不透传原文案由 ChatDrawer 统一映射「刷新重试/订单负责人可能已变更」;住宿安排卡加「联系团期管理员」(显隐只看 itinerary.groupBatchId 非空不看 OrderMainVO.groupBatchId,无定制师显「暂无定制师」,角标 itineraryGroupUnreadCount),团期「查看需求」名单表每户加「联系定制师」(仅 group-batch:demand:confirm 持码露出,团队共享「待处理」角标,操作列宽 76→150 必要调宽);抽屉头徽章透传后端 peerRoleLabel,前端不建 GROUP_ADMIN 硬编码映射;SSE JSON 解析宽容未知字段零改动,聊天 Tab unread-total 与消息中心 unread-count 两角标按契约分开;定向 114 例+回归 87 文件 918 例全绿,对抗 review PASS,checkpoint 全绿(Vitest 全量+生产构建)。"
|
||
updated_at: "2026-09-08"
|
||
base: "dev-v3"
|
||
---
|
||
|
||
# 团期模块：定制师 ↔ 团期管理员站内会话（GROUP:{orderId}）
|
||
|
||
> **服务**: `hl-order-service-v3`、`hl-user-service`
|
||
> **Issue**: #7211
|
||
> **PR**: #7225（order-v3）、#7226（user-service）
|
||
> **日期**: 2026-09-07
|
||
> **影响范围**: 管理后台子订单详情「住宿安排」卡、团期详情「查看需求」名单表
|
||
|
||
## ⚠️ 关键变化
|
||
|
||
**新增团期管理员团队会话通道**：定制师与团期管理员团队（而非指派个人）按子订单维度建立实时对话（会话键 `GROUP:{orderId}`），镜像车务团队制（团队共享未读水位行、定制师广播落池、任一管理员读即全员清零）。
|
||
|
||
**顶部角标两条规则分开**：
|
||
1. 团期管理员团队共享池（`admin_id=0`）未读**只计入**聊天 Tab 与 SSE，**不计入**消息中心角标；
|
||
2. 团期管理员回复落定制师个人行（`sender_role=GROUP_ADMIN`），照常计入定制师顶部角标、消息中心与收件箱。
|
||
|
||
**前端勾选要点**：
|
||
- `ItineraryVO.groupBatchId` 非空时才显示「联系团期管理员」按钮（**不看** `OrderMainVO.groupBatchId`）；
|
||
- `peerOnline` 按账号在线判定，不承诺"几分钟内回复"；
|
||
- 无定制师时 `peerName=null` 展示「暂无定制师」；
|
||
- 281002 权限错误不透传原文案，用「刷新重试 / 订单负责人可能已变更」；
|
||
- `groupChatUnreadCount` 是团队共享「待处理」，任一管理员读即全员清零。
|
||
|
||
---
|
||
|
||
## 二、变更接口清单
|
||
|
||
| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
|
||
|---|------|------|------|----------|------|
|
||
| 1 | 开启团期管理员会话（新增） | POST | `/admin/message/chat/open-group` | 新增接口 | 定制师 ↔ 团期管理员团队会话，键 `GROUP:{orderId}` |
|
||
| 2 | 开启会话（通用，GROUP 分流） | POST | `/admin/message/chat/open` | 修改接口 | `bizModule` 新增 `GROUP`，分流到 open-group（`peerAdminId` 忽略，不产生 pair 键） |
|
||
| 3 | 会话列表 | GET | `/admin/message/chat/conversations` | 修改接口 | `bizModule` 过滤新增 `GROUP`；`peerRole / peerRoleLabel` 新增 `GROUP_ADMIN / 团期管理员`；持码者团队共享未读 |
|
||
| 4 | 消息列表 | GET | `/admin/message/chat/{conversationKey}/messages` | 修改接口 | 支持 `GROUP:{orderId}` 键；`senderRole` 新增 `GROUP_ADMIN` |
|
||
| 5 | 发送消息 | POST | `/admin/message/chat/{conversationKey}/messages` | 修改接口 | 定制师发 → 团队池；管理员发 → 定制师个人行 |
|
||
| 6 | 标记已读 | POST | `/admin/message/chat/{conversationKey}/read` | 修改接口 | 持码者读 → 团队水位推进、全员清零、定制师收 `im-chat-read` |
|
||
| 7 | 聊天 Tab 未读总数 | GET | `/admin/message/chat/unread-total` | 修改接口 | 当前角色持码时合入 GROUP 团队池未读 |
|
||
| 8 | 子订单行程（住宿安排卡） | GET | `/v3/admin/order/{id}/itinerary` | 修改接口 | 新增 `groupBatchId`（按钮显隐依据）、`groupUnreadMessageCount` |
|
||
| 9 | 团期子订单名单 | GET | `/v3/admin/order/group-batch/{groupBatchId}/orders` | 修改接口 | 每项新增 `groupChatUnreadCount`（团队共享「待处理」） |
|
||
|
||
**SSE 契约**（`/ws/admin-msg/stream`，事件 `im-chat` / `im-chat-read`，非 REST）：payload 新增 `targetPermissionCode`（String，可空）；GROUP 团队信令为 `"group-batch:demand:confirm"`，只投递给当前角色持码的连接（实测：持码 ADMIN 收到，不持码 CUSTOMIZER 收不到，同一账号切到不持码角色后的旧连接也收不到）。`im-chat-read` 示例：`{"adminId":1002,"type":"READ","conversationKey":"GROUP:2096701865117831170","readerAdminId":1001,"lastReadMessageId":"2096701909673943042"}`。前端无需改解析，但请确认 SSE JSON 解析不拒绝未知字段。
|
||
|
||
**内部 Feign**（不经网关，前端不用）：`POST /internal/message/chat/biz-unread-batch` `bizModule` 新增 `GROUP`（`unreadScope` TEAM / PERSONAL）；`POST /internal/message/chat/reconcile-fleet-consultant` 路径不变、同时收敛 FLEET 与 GROUP；order-v3 `POST /internal/house/order-chat-summary-batch` 新增 `groupBatchId / groupBatchNo`。
|
||
|
||
---
|
||
|
||
## 三、接口详情
|
||
|
||
### 1. 开启团期管理员会话 `POST /admin/message/chat/open-group`
|
||
|
||
**VO**: `ChatOpenGroupReqVO → ChatOpenFullRespVO`
|
||
|
||
#### 使用场景
|
||
|
||
定制师或团期管理员打开与对方团队的会话；调用方为 hl-ui 子订单详情「住宿安排」卡「联系团期管理员」、团期详情「查看需求」名单表「联系定制师」。
|
||
|
||
#### 入参字段表
|
||
|
||
| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|
||
|---|---|---|---|---|---|
|
||
| `orderId` | Body | Long(String) | ✓ | @NotNull | 子订单 ID；**不接受** `peerAdminId`（传了被忽略） |
|
||
|
||
#### 出参字段表
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|---|---|---|
|
||
| `conversationKey` | String | `GROUP:{orderId}` |
|
||
| `isNew` | Boolean | 开方成员行此前是否不存在 |
|
||
| `peerAdminId` | Long | 定制师视角恒 0（团队占位）；管理员视角 = 当前定制师 adminId（无定制师时 0） |
|
||
| `peerName` | String | 定制师视角「团期管理员」；管理员视角 = 定制师姓名快照，**无定制师时 null**，前端展示「暂无定制师」 |
|
||
| `peerRole` | String | 定制师视角 `GROUP_ADMIN`；管理员视角 `CUSTOMIZER` |
|
||
| `peerRoleLabel` | String | 「团期管理员」或「定制师」 |
|
||
| `peerOnline` | Boolean | 定制师视角 = 任一持码活跃账号在线；管理员视角 = 定制师在线。**按账号在线判定，不按当前角色**，不保证对方能立刻收到消息 |
|
||
| `unreadCount` | Integer | 恒 0（打开即已读） |
|
||
| `order` | ChatOrderCardVO | 订单卡：orderNo / teamNo / customerName / destination / tripDays / productName / adultCount / childCount / **groupBatchNo**(String) / **groupBatchId**(String)；摘要不可达时为 null |
|
||
| `thread` | ChatThreadRespVO | 最新消息线索：conversationKey / hasMore / nextCursor / list[] 消息数组 |
|
||
| `unreadTotal` | Integer | 标记已读后顶部合并未读总数（不含 GROUP 团队池，与 unread-count REST 保持一致） |
|
||
|
||
#### 请求示例
|
||
|
||
```json
|
||
POST /admin/message/chat/open-group
|
||
|
||
{
|
||
"orderId": 60123456789001
|
||
}
|
||
```
|
||
|
||
#### 响应示例
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "成功",
|
||
"success": true,
|
||
"data": {
|
||
"conversationKey": "GROUP:60123456789001",
|
||
"isNew": false,
|
||
"peerAdminId": 0,
|
||
"peerName": "团期管理员",
|
||
"peerRole": "GROUP_ADMIN",
|
||
"peerRoleLabel": "团期管理员",
|
||
"peerOnline": true,
|
||
"unreadCount": 0,
|
||
"order": {
|
||
"orderNo": "HL2609010001",
|
||
"teamNo": "T20260901001",
|
||
"customerName": "李四",
|
||
"destination": "三亚",
|
||
"tripDays": 4,
|
||
"productName": "豪华蜜月游",
|
||
"adultCount": 2,
|
||
"childCount": 0,
|
||
"groupBatchNo": "G20260901001",
|
||
"groupBatchId": "1867000000001"
|
||
},
|
||
"thread": {
|
||
"conversationKey": "GROUP:60123456789001",
|
||
"hasMore": false,
|
||
"nextCursor": null,
|
||
"list": []
|
||
},
|
||
"unreadTotal": 0
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 空数据 / 降级响应
|
||
|
||
摘要不可达或缺失时，`order` 为 null；`thread.list` 可为空。
|
||
|
||
#### 错误响应
|
||
|
||
```json
|
||
{
|
||
"code": 281002,
|
||
"message": "无权访问该会话",
|
||
"success": false,
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
#### 业务边界条目
|
||
|
||
- 打开即标记已读，`unreadCount` 恒 0
|
||
- 团队水位行 `admin_id=0` 自动创建，定制师与管理员各有成员行
|
||
- 定制师视角 `peerRole=GROUP_ADMIN`；管理员视角 `peerRole=CUSTOMIZER`
|
||
- 无定制师的新团期：按钮不显示（`groupBatchId` 为空），`peerName` 返 null
|
||
- 转单后旧定制师再开 → 281002，新定制师开 → 200 且承接未读
|
||
|
||
---
|
||
|
||
---
|
||
|
||
---
|
||
|
||
### 2. 开启会话（通用，GROUP 分流） `POST /admin/message/chat/open`
|
||
|
||
**VO**: `ChatOpenReqVO → ChatOpenFullRespVO`
|
||
|
||
#### 使用场景
|
||
旧客户端沿用通用入口时传 `bizModule=GROUP`；新代码直接用 `open-group`。两者同一实现。
|
||
|
||
#### 入参字段表
|
||
| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|
||
|---|---|---|---|---|---|
|
||
| `bizModule` | Body | String | ✓ | — | 新增枚举值 `GROUP`（原 HOUSE / FLEET / DIRECT） |
|
||
| `bizId` | Body | Long(String) | ✓ | — | 团期子订单 ID |
|
||
| `peerAdminId` | Body | Long(String) | — | — | GROUP 下忽略：团队会话不按对端个人建键 |
|
||
|
||
#### 出参字段表
|
||
| 字段 | 类型 | 说明 |
|
||
|---|---|---|
|
||
| conversationKey | String | `GROUP:{orderId}` |
|
||
| 其余字段 | — | 与 `open-group` 完全相同（见 1） |
|
||
|
||
#### 请求示例
|
||
```json
|
||
POST /admin/message/chat/open
|
||
{"bizModule": "GROUP", "bizId": "2096701865117831170", "peerAdminId": "123"}
|
||
```
|
||
|
||
#### 响应示例
|
||
```json
|
||
{"code": 200, "message": "成功", "success": true, "data": {"conversationKey": "GROUP:2096701865117831170", "isNew": false, "peerAdminId": "0", "peerName": "团期管理员", "peerRole": "GROUP_ADMIN", "peerRoleLabel": "团期管理员", "peerOnline": true, "unreadCount": 0, "order": {"orderNo": "HL20260907044734031", "groupBatchNo": "Q202610012052935476548939777", "groupBatchId": "2096412454643802114"}, "thread": {"conversationKey": "GROUP:2096701865117831170", "hasMore": false, "list": []}, "unreadTotal": 1}}
|
||
```
|
||
|
||
#### 空数据 / 降级响应
|
||
同 `open-group`：order-v3 不可达时 `order` 为 null（会话仍可开）。
|
||
|
||
#### 错误响应
|
||
```json
|
||
{"code": 281002, "message": "无权访问该会话", "data": null, "success": false}
|
||
```
|
||
| 码 | 触发 |
|
||
|---|---|
|
||
| 281002 | 非该单当前定制师且当前角色不持 `group-batch:demand:confirm`；转单后旧定制师；order-v3 摘要不可达（失败关闭）。前端不透传原文案，用「刷新重试 / 订单负责人可能已变更」 |
|
||
| 281015 | 非团期子订单 |
|
||
| 281012 | bizId 为空 |
|
||
|
||
#### 业务边界条目
|
||
- 实测 `peerAdminId=123` 也返回 `GROUP:{orderId}`，库内不出现 `GROUP:{id}:{a}:{b}` pair 键。
|
||
|
||
---
|
||
|
||
### 3. 会话列表 `GET /admin/message/chat/conversations`
|
||
|
||
**VO**: `查询参数 → PageResult<ChatConversationRespVO>`
|
||
|
||
#### 使用场景
|
||
聊天 Tab 列表。团期管理员（持码角色）看到所有团期子订单的 GROUP 会话（团队共享未读）；定制师看到自己名下团单的 GROUP 会话；不持码 ADMIN / 其他定制师看不到。
|
||
|
||
#### 入参字段表
|
||
| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|
||
|---|---|---|---|---|---|
|
||
| `bizModule` | Query | String | — | — | 新增 `GROUP`；不传时非团队模块列表**排除** FLEET / GROUP 团队行（与既有 FLEET 规则一致） |
|
||
| `pageNo / pageSize` | Query | Integer | — | — | 不变 |
|
||
|
||
#### 出参字段表
|
||
| 字段 | 类型 | 说明 |
|
||
|---|---|---|
|
||
| list[].bizModule | String | `GROUP` |
|
||
| list[].peerRole / peerRoleLabel | String | 定制师视角 `GROUP_ADMIN` / 团期管理员；管理员视角 `CUSTOMIZER` / 定制师 |
|
||
| list[].peerName | String | 定制师视角「团期管理员」；管理员视角定制师姓名 |
|
||
| list[].peerOnline | Boolean | 定制师视角 = 任一持码活跃账号在线（按账号不按当前角色，不保证对方能立刻收到） |
|
||
| list[].unreadCount | Integer | 持码者为团队共享未读（任一持码者读即全员清零） |
|
||
| list[].orderNo / teamNo | String | 订单号 / 团号 enrich |
|
||
|
||
#### 请求示例
|
||
```json
|
||
GET /admin/message/chat/conversations?pageNo=1&pageSize=50&bizModule=GROUP
|
||
```
|
||
|
||
#### 响应示例
|
||
```json
|
||
{"code": 200, "message": "成功", "success": true, "data": {"list": [{"conversationKey": "GROUP:2096701865117831170", "bizModule": "GROUP", "orderNo": "HL20260907044734031", "teamNo": "26-4983", "peerRole": "CUSTOMIZER", "peerRoleLabel": "定制师", "peerName": "test_admin", "unreadCount": 0, "peerOnline": true}], "total": 1}}
|
||
```
|
||
|
||
#### 空数据 / 降级响应
|
||
不持码的 ADMIN / 其他定制师：`list=[]`（实测 0 条）；无角色 token 对团队模块失败关闭返空页。
|
||
|
||
#### 错误响应
|
||
```json
|
||
{"code": 401, "message": "Token无效或已过期", "data": null, "success": false}
|
||
```
|
||
| 码 | 触发 |
|
||
|---|---|
|
||
| 401 | 未登录 / token 失效（沿用既有） |
|
||
|
||
#### 业务边界条目
|
||
- 会话卡 `peerRole` 与消息气泡 `senderRole` 的中文映射都要补 `GROUP_ADMIN → 团期管理员`。
|
||
- 未读语义是团队共享「待处理」，别写成「你的未读」。
|
||
|
||
---
|
||
|
||
### 4. 消息列表 `GET /admin/message/chat/{conversationKey}/messages`
|
||
|
||
**VO**: `查询参数 → ChatThreadRespVO`
|
||
|
||
#### 使用场景
|
||
打开 GROUP 会话后拉取历史；`conversationKey=GROUP:{orderId}`。
|
||
|
||
#### 入参字段表
|
||
| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|
||
|---|---|---|---|---|---|
|
||
| `conversationKey` | Path | String | ✓ | — | `GROUP:{orderId}` |
|
||
| `cursor / pageSize` | Query | — | — | — | 不变 |
|
||
|
||
#### 出参字段表
|
||
| 字段 | 类型 | 说明 |
|
||
|---|---|---|
|
||
| list[].senderRole | String | 新增 `GROUP_ADMIN`（管理员回复）；定制师广播为 null |
|
||
| list[].readByPeer | Boolean | 任一持码者读后为 true（`im-chat-read` 同步推送） |
|
||
|
||
#### 请求示例
|
||
```json
|
||
GET /admin/message/chat/GROUP:2096701865117831170/messages?pageSize=20
|
||
```
|
||
|
||
#### 响应示例
|
||
```json
|
||
{"code": 200, "message": "成功", "success": true, "data": {"conversationKey": "GROUP:2096701865117831170", "hasMore": false, "nextCursor": null, "list": [{"messageId": "2096701935376617473", "senderAdminId": "1001", "senderName": "admin", "senderRole": "GROUP_ADMIN", "msgType": "TEXT", "content": "管理员回复 1", "isMine": false, "readByPeer": false}]}}
|
||
```
|
||
|
||
#### 空数据 / 降级响应
|
||
无消息时 `list=[]`。
|
||
|
||
#### 错误响应
|
||
```json
|
||
{"code": 281002, "message": "无权访问该会话", "data": null, "success": false}
|
||
```
|
||
| 码 | 触发 |
|
||
|---|---|
|
||
| 281002 | 非该单当前定制师且当前角色不持 `group-batch:demand:confirm`；转单后旧定制师；order-v3 摘要不可达（失败关闭）。前端不透传原文案，用「刷新重试 / 订单负责人可能已变更」 |
|
||
|
||
#### 业务边界条目
|
||
- 定制师端消息气泡对 `senderRole=GROUP_ADMIN` 显示「团期管理员」徽章。
|
||
|
||
---
|
||
|
||
### 5. 发送消息 `POST /admin/message/chat/{conversationKey}/messages`
|
||
|
||
**VO**: `ChatMessageSendReqVO → ChatMessageSendRespVO`
|
||
|
||
#### 使用场景
|
||
定制师发 → 落团队池（全体持码者共享未读，SSE `im-chat` 定向到持码连接）；管理员发 → 落定制师个人行（定制师顶部角标 / 收件箱照常 +1）。
|
||
|
||
#### 入参字段表
|
||
| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|
||
|---|---|---|---|---|---|
|
||
| `conversationKey` | Path | String | ✓ | — | `GROUP:{orderId}` |
|
||
| `content` | Body | String | ✓ | — | 不变 |
|
||
| `priority / msgType` | Body | String | — | — | 不变 |
|
||
|
||
#### 出参字段表
|
||
| 字段 | 类型 | 说明 |
|
||
|---|---|---|
|
||
| messageId | String | 不变 |
|
||
|
||
#### 请求示例
|
||
```json
|
||
POST /admin/message/chat/GROUP:2096701865117831170/messages
|
||
{"content": "请确认第二晚房型"}
|
||
```
|
||
|
||
#### 响应示例
|
||
```json
|
||
{"code": 200, "message": "成功", "success": true, "data": {"messageId": "2096701909673943042"}}
|
||
```
|
||
|
||
#### 空数据 / 降级响应
|
||
无。
|
||
|
||
#### 错误响应
|
||
```json
|
||
{"code": 281002, "message": "无权访问该会话", "data": null, "success": false}
|
||
```
|
||
| 码 | 触发 |
|
||
|---|---|
|
||
| 281002 | 非该单当前定制师且当前角色不持 `group-batch:demand:confirm`；转单后旧定制师；order-v3 摘要不可达（失败关闭）。前端不透传原文案，用「刷新重试 / 订单负责人可能已变更」 |
|
||
|
||
#### 业务边界条目
|
||
- 转单与 GROUP 发送 / 已读 / 开会话互斥（order-v3 转单入口与 user-service 共用同一把 `GROUP:{orderId}` 锁）；实测与转单并发的发送被串行后按新归属拒绝（281002）。
|
||
- 新增 GROUP 日志只打标识符，不打客户姓名 / 消息内容。
|
||
|
||
---
|
||
|
||
### 6. 标记已读 `POST /admin/message/chat/{conversationKey}/read`
|
||
|
||
**VO**: `无 body → ChatReadRespVO`
|
||
|
||
#### 使用场景
|
||
持码者读 → 团队水位推进、全员未读清零、给定制师补发 `im-chat-read`；定制师读 → 只推进自己行。
|
||
|
||
#### 入参字段表
|
||
| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|
||
|---|---|---|---|---|---|
|
||
| `conversationKey` | Path | String | ✓ | — | `GROUP:{orderId}` |
|
||
|
||
#### 出参字段表
|
||
| 字段 | 类型 | 说明 |
|
||
|---|---|---|
|
||
| unreadTotal | Integer | 标记后的顶部合并未读（不含 GROUP 团队池） |
|
||
|
||
#### 请求示例
|
||
```json
|
||
POST /admin/message/chat/GROUP:2096701865117831170/read
|
||
```
|
||
|
||
#### 响应示例
|
||
```json
|
||
{"code": 200, "message": "成功", "success": true, "data": {"unreadTotal": 13}}
|
||
```
|
||
|
||
#### 空数据 / 降级响应
|
||
无。
|
||
|
||
#### 错误响应
|
||
```json
|
||
{"code": 281002, "message": "无权访问该会话", "data": null, "success": false}
|
||
```
|
||
| 码 | 触发 |
|
||
|---|---|
|
||
| 281002 | 非该单当前定制师且当前角色不持 `group-batch:demand:confirm`；转单后旧定制师；order-v3 摘要不可达（失败关闭）。前端不透传原文案，用「刷新重试 / 订单负责人可能已变更」 |
|
||
|
||
#### 业务边界条目
|
||
- 实测管理员读后名单表两持码账号 `groupChatUnreadCount` 同时 1→0，定制师收到 `im-chat-read`（`readerAdminId` 为读的管理员）。
|
||
|
||
---
|
||
|
||
### 7. 聊天 Tab 未读总数 `GET /admin/message/chat/unread-total`
|
||
|
||
**VO**: `无参 → ChatUnreadTotalRespVO`
|
||
|
||
#### 使用场景
|
||
聊天 Tab 角标。**当前角色持码时合入 GROUP 团队池未读**；消息中心 `GET /admin/message/unread-count` 与顶部合并角标**不含**团队池。
|
||
|
||
#### 入参字段表
|
||
| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|
||
|---|---|---|---|---|---|
|
||
| （无） | — | — | — | — | 无入参 |
|
||
|
||
#### 出参字段表
|
||
| 字段 | 类型 | 说明 |
|
||
|---|---|---|
|
||
| chatUnreadTotal | Integer | 持码者 = 个人未读 + GROUP 团队池未读（+ FLEET 池，车务管理员） |
|
||
|
||
#### 请求示例
|
||
```json
|
||
GET /admin/message/chat/unread-total
|
||
```
|
||
|
||
#### 响应示例
|
||
```json
|
||
{"code": 200, "message": "成功", "success": true, "data": {"chatUnreadTotal": 3}}
|
||
```
|
||
|
||
#### 空数据 / 降级响应
|
||
无。
|
||
|
||
#### 错误响应
|
||
```json
|
||
{"code": 401, "message": "Token无效或已过期", "data": null, "success": false}
|
||
```
|
||
| 码 | 触发 |
|
||
|---|---|
|
||
| 401 | 未登录 / token 失效 |
|
||
|
||
#### 业务边界条目
|
||
- 实测定制师广播后持码 ADMIN 的 `chat/unread-total` 2→3，而 `/admin/message/unread-count` 13→13。
|
||
- 定制师收到管理员回复 → 个人行 → `unread-count` 0→1，前端不得过滤 `senderRole=GROUP_ADMIN` 的行。
|
||
|
||
---
|
||
|
||
### 8. 子订单行程（住宿安排卡） `GET /v3/admin/order/{id}/itinerary`
|
||
|
||
**VO**: `ItineraryVO`
|
||
|
||
#### 使用场景
|
||
子订单详情「住宿安排」卡：「联系团期管理员」按钮显隐 + 角标。
|
||
|
||
#### 入参字段表
|
||
| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|
||
|---|---|---|---|---|---|
|
||
| `id` | Path | Long | ✓ | — | 子订单 ID |
|
||
|
||
#### 出参字段表
|
||
| 字段 | 类型 | 说明 |
|
||
|---|---|---|
|
||
| groupBatchId | String | 新增。统一归团解析结果（含历史兼容单 `product_batch_id` 反查）；普通单 null。**按钮显隐只看它，不看 `OrderMainVO.groupBatchId`** |
|
||
| groupUnreadMessageCount | Integer | 新增。当前登录定制师在本单 GROUP 会话的个人未读；非团单 / 降级 / 未登录 0 |
|
||
|
||
#### 请求示例
|
||
```json
|
||
GET /v3/admin/order/2096701865117831170/itinerary
|
||
```
|
||
|
||
#### 响应示例
|
||
```json
|
||
{"code": 200, "message": "成功", "success": true, "data": {"groupBatchId": "2096412454643802114", "groupUnreadMessageCount": 1, "unreadMessageCount": 0}}
|
||
```
|
||
|
||
#### 空数据 / 降级响应
|
||
普通单：`"groupBatchId": null, "groupUnreadMessageCount": 0`；user-service 不可达 → `groupUnreadMessageCount=0`，其余字段正常。
|
||
|
||
#### 错误响应
|
||
```json
|
||
{"code": 582001, "message": "订单不存在", "data": null, "success": false}
|
||
```
|
||
| 码 | 触发 |
|
||
|---|---|
|
||
| 582001 | 订单不存在（沿用既有） |
|
||
|
||
#### 业务边界条目
|
||
- `groupBatchId` 与 `OrderMainVO.groupBatchId` 语义不同（后者是原始列，历史兼容单可能为空）。
|
||
|
||
---
|
||
|
||
### 9. 团期子订单名单 `GET /v3/admin/order/group-batch/{groupBatchId}/orders`
|
||
|
||
**VO**: `查询参数 → List<GroupBatchOrderItemRespVO>`
|
||
|
||
#### 使用场景
|
||
团期详情「查看需求」名单表每户「联系定制师」+ 角标。
|
||
|
||
#### 入参字段表
|
||
| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|
||
|---|---|---|---|---|---|
|
||
| `groupBatchId` | Path | Long | ✓ | — | 团期 ID |
|
||
| `includeTravelers / includeNeeds / includeCancelled` | Query | Boolean | — | — | 不变 |
|
||
|
||
#### 出参字段表
|
||
| 字段 | 类型 | 说明 |
|
||
|---|---|---|
|
||
| [].groupChatUnreadCount | Integer | 新增。团队共享「待处理」未读（TEAM 口径）：任一管理员读即全员清零，**不是**当前登录人个人未读；降级 0 |
|
||
|
||
#### 请求示例
|
||
```json
|
||
GET /v3/admin/order/group-batch/2096412454643802114/orders
|
||
```
|
||
|
||
#### 响应示例
|
||
```json
|
||
{"code": 200, "message": "成功", "success": true, "data": [{"orderId": "2096701865117831170", "orderNo": "HL20260907044734031", "groupChatUnreadCount": 1}]}
|
||
```
|
||
|
||
#### 空数据 / 降级响应
|
||
user-service 不可达或超时 → 全部 0，主列表照常返回。
|
||
|
||
#### 错误响应
|
||
```json
|
||
{"code": 589507, "message": "无操作权限（非团期管理员 / 非本定制师名下）", "data": null, "success": false}
|
||
```
|
||
| 码 | 触发 |
|
||
|---|---|
|
||
| 589507 | 无 `group-batch:view`（沿用既有守卫） |
|
||
| 589500 | 团期不存在 |
|
||
|
||
#### 业务边界条目
|
||
- 文案用「待处理 / 待回复」而非「未读消息」；本字段只供页面级加载，不要做高频轮询。
|
||
|
||
---
|
||
|
||
## 四、契约约束与正确调用方式
|
||
|
||
### 授权规则
|
||
|
||
会话准入：①当前定制师本人（token 角色 CUSTOMIZER 且 me == consultant_id）或②团期管理员（token 当前角色持权限码 `group-batch:demand:confirm`）；均不满足返 281002。
|
||
|
||
### 转单锁定
|
||
|
||
order-v3 转单入口：FLEET 锁 → 判团 → GROUP 锁 → 事务。普通单不取 GROUP 锁。并发互斥。
|
||
|
||
---
|
||
|
||
## 五、数据库行为
|
||
|
||
- **无表结构变更、无 DDL**（现有列宽已足）；
|
||
- **权限种子** `V20260906_006`（INSERT 权限码 + 关联）由 #7210 落地；若本单先合则自带；
|
||
- **数据形态**：admin_message 新增 bizModule=GROUP 行；sender_role=NULL（定制师广播）或 GROUP_ADMIN（管理员回复）；admin_conversation_member 新增 admin_id=0 团队行与个人行。
|
||
|
||
---
|
||
|
||
## 六、边界行为
|
||
|
||
- 打开即已读；团队水位行自动创建；
|
||
- 定制师广播到全体持码账号；无定制师时 peerName=null；
|
||
- 权限缓存 TTL 10 分钟；撤权生效靠 TTL 或运维 `DEL admin_permissions:v2:role:{roleKey}`；
|
||
- 团期软删时订单卡 `groupBatchNo=null`；前端用「团期已归档」占位。
|
||
|
||
---
|
||
|
||
## 七、不影响范围
|
||
|
||
- 车务（FLEET）聊天流程与数据；
|
||
- 房 / 车需求创建/修改；
|
||
- 抢单池流程；
|
||
- 消息中心界面（GROUP 池行暂未纳管，后续单独工单）；
|
||
- 网关路由。
|
||
|
||
---
|
||
|
||
## 八、测试环境已验证
|
||
|
||
- 部署：dev-v3 `072a476be`（PR-A #7225，order-v3）+ `f4251d946`（PR-B #7226，user-service），测试服 `BRANCH=dev-v3 deploy-backend.sh` 两服务已滚；lock4j 键前缀两服务均默认值。
|
||
- 网关实测（团 A `2096412454643802114`，定制师 test_admin / 持码 ADMIN admin / SUPER_ADMIN wx / 不持码 qulili）：AC-1 open-group 200（`GROUP:{orderId}`、`peerRole=GROUP_ADMIN`、订单卡 `groupBatchNo=Q202610012052935476548939777` / `groupBatchId`）；AC-2 普通单 281015；AC-3 不持码 281002、短信登录临时 CUSTOMIZER（DB 角色 ADMIN）281002、撤码后 `DEL admin_permissions:v2:role:ADMIN` → 281002、恢复 → 200；AC-4 未提需求 200；AC-5 定制师广播落 `admin_id=0` 池行、名单表 TEAM 未读两账号同值 1、管理员读后全员 0 且定制师收 `im-chat-read`；AC-6 管理员回复落定制师个人行 `sender_role=GROUP_ADMIN`、SSE `im-chat` 到达、itinerary `groupUnreadMessageCount=1`、`unread-count` 0→1；AC-7 持码 ADMIN 收到含 `targetPermissionCode` 的 `im-chat`、不持码收不到、切角色旧连接收不到，`chat/unread-total` 2→3 而 `unread-count` 不变；AC-8 会话列表 GROUP 过滤命中（orderNo / teamNo / peerRoleLabel）、不持码 0 条；AC-9 通用 open 同键无 pair 键；AC-10 转单后旧行 ARCHIVED / 新行 ACTIVE / 旧定制师 281002、并发发送被串行后拒绝；AC-10b 历史兼容单 open-group 200 且 itinerary `groupBatchId` 非空；AC-12 / AC-13 字段与上述一致。
|
||
|
||
---
|
||
|
||
## 十、相关文档
|
||
|
||
- 工单正文：#7211
|
||
- 架构方案：#7211 评论「架构方案」
|
||
- 接口文档：docs/group/团期模块接口文档-v2.0.html §0C.11.3
|
||
|
||
---
|
||
|
||
## 关联 / 联系人
|
||
|
||
### 链接
|
||
|
||
- **Issue**: [#7211](https://git.1814.love:8443/wx/HL/issues/7211)
|
||
- **PR（order-v3）**: [#7225](https://git.1814.love:8443/wx/HL/pulls/7225)
|
||
- **PR（user-service）**: [#7226](https://git.1814.love:8443/wx/HL/pulls/7226)
|
||
|
||
### 联系人
|
||
|
||
- **后端负责人**: wx
|
||
- **前端负责人（hl-ui）**: mmg
|