From 9b43fcc0d941ee273b73543fab37504bc74cf0ef Mon Sep 17 00:00:00 2001 From: API Changelog Bot Date: Fri, 19 Jun 2026 17:48:41 +0800 Subject: [PATCH] =?UTF-8?q?docs(changelog-v2):=20=E7=AB=99=E5=86=85?= =?UTF-8?q?=E4=BF=A1=E8=81=8A=E5=A4=A9=E4=BC=9A=E8=AF=9D=E5=88=97=E8=A1=A8?= =?UTF-8?q?=20enrich=E2=80=94=E2=80=94=E5=A4=B4=E5=83=8F/=E8=AE=A2?= =?UTF-8?q?=E5=8D=95=E6=91=98=E8=A6=81/=E4=B8=9A=E5=8A=A1=E7=8A=B6?= =?UTF-8?q?=E6=80=81/=E5=BE=85=E5=9B=9E=E5=A4=8Dtab=20+=20=E6=94=B6?= =?UTF-8?q?=E4=BB=B6=E7=AE=B1=E6=B6=88=E6=81=AF=E7=B1=BB=E5=9E=8B=20(#4066?= =?UTF-8?q?)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- ...enrich-头像订单摘要待回复tab+消息类型-管理后台.md | 124 ++++++++++++++++++ 1 file changed, 124 insertions(+) create mode 100644 changelogs-v2/2026-06/19_4066_站内信聊天会话列表enrich-头像订单摘要待回复tab+消息类型-管理后台.md diff --git a/changelogs-v2/2026-06/19_4066_站内信聊天会话列表enrich-头像订单摘要待回复tab+消息类型-管理后台.md b/changelogs-v2/2026-06/19_4066_站内信聊天会话列表enrich-头像订单摘要待回复tab+消息类型-管理后台.md new file mode 100644 index 0000000..25287b7 --- /dev/null +++ b/changelogs-v2/2026-06/19_4066_站内信聊天会话列表enrich-头像订单摘要待回复tab+消息类型-管理后台.md @@ -0,0 +1,124 @@ +# 站内信聊天会话列表 enrich — 头像/订单摘要/业务状态/待回复 tab + 收件箱消息类型 + +- **变更类型**：字段新增（接口增强）+ 新增 internal 端点 +- **端类型**：管理后台 +- **日期**：2026-06-19 +- **Issue**：[#4066](https://git.1814.love:8443/wx/HL/issues/4066) +- **PR**：[#4084](https://git.1814.love:8443/wx/HL/pulls/4084) +- **后端负责人**：王骁 + +--- + +## 🛑 前端暂不需要接入（最高优先级） + +**本次仅「后端」就绪，前端聊天 UI 集成暂缓——收到本文先不用动工。** 本文档是后端接口的**提前留档/参考**，**不是开工通知**；待产品排期、正式通知前端接入时再据此对接。 + +--- + +## ⚠️ 关键说明（前端正式接入时再读） + +1. **会话列表卡片直接吃后端字段**。每张会话卡需要的「头像 + 订单号 + 订单摘要（联系人·目的地·天数）+ 业务状态标签 + 待回复」后端已在 `GET /admin/message/chat/conversations` 一次返齐，前端不用再二次拉订单。 +2. **订单维度字段只对 HOUSE 会话有值**。`orderNo/customerName/destination/tripDays/bizStatusLabel/progressDesc` 仅房务会话（`bizModule=HOUSE`）填充；FLEET 车务、DIRECT 直聊会话这些字段留空（车务业务状态接入 deferred）。 +3. **订单信息是实时取、不冗余落库**。后端按订单 id 实时向 order-v3 取摘要，order-v3 临时不可达时这些字段**整体留空、会话列表照常返回**（软依赖降级），前端按「有值才渲染」处理即可。 +4. **「待回复 / 全部会话」两个 tab**：全部会话 = 不传 `onlyPending`；待回复 tab = `onlyPending=true`（只返本人有未读的会话）。卡片上的「待回复」角标 = `pendingReply` 字段。 +5. **收件箱「订单消息 / 普通消息」类型**：`GET /admin/message/list` 每条新增 `messageType`/`messageTypeLabel`，前端可据此分组/打标。订单消息只是站内信的一种视图分类，不是独立的消息体系。 + +--- + +## 1. 背景 + +聊天会话列表原型要求每张会话卡展示：头像 + 角色（房务专员/车务专员）+ 订单号 + 订单摘要（客户·目的地·天数）+ 最后消息 + 业务状态标签 + 待回复按钮，顶部「待回复 / 全部会话」tab。原 P1 会话列表只返了对方名/角色/未读/预览/时间，缺头像与订单维度信息。本次按方案 A（user-service enrich，订单维度信息 Feign 取 order-v3）一次补齐，并顺带给收件箱站内信补「消息类型」。 + +--- + +## 2. 变更清单 + +| 序号 | 接口 | 变更 | 类型 | +|------|------|------|------| +| 1 | `GET /admin/message/chat/conversations` | 出参补 8 字段（头像/订单摘要/状态/待回复）+ 入参加 `onlyPending` | 🔧 字段新增 | +| 2 | `POST /internal/house/order-chat-summary-batch` | order-v3 新增（会话列表 enrich 数据源，内部 Feign，前端不直连） | ✨ 新增 internal 端点 | +| 3 | `GET /admin/message/list` | 出参补 `messageType`/`messageTypeLabel` | 🔧 字段新增 | + +--- + +## 3. 会话列表 `GET /admin/message/chat/conversations` + +### 3.1 入参新增 + +| 参数 | 类型 | 必填 | 说明 | +|------|------|------|------| +| `onlyPending` | Boolean | 否 | 仅看待回复（`true`=只返本人未读>0 的会话，「待回复」tab）；空/`false`=全部会话 | + +（原有 `bizModule` / `bizId` / `pageNo` / `pageSize` 不变。） + +### 3.2 出参 `records[]` 新增字段（原字段保留） + +| 字段 | 类型 | 说明 | +|------|------|------| +| `peerAvatar` | String | 对方头像 URL（自定义 > 企微 > null，可空） | +| `orderNo` | String | 订单号（仅 HOUSE 会话有，非 HOUSE / order-v3 不可达留空） | +| `customerName` | String | 订单联系人姓名（仅 HOUSE 会话） | +| `destination` | String | 目的地（房务行程城市「-」拼，仅 HOUSE，无可解析城市时 null） | +| `tripDays` | Integer | 行程天数（仅 HOUSE 会话） | +| `bizStatusLabel` | String | 业务状态中文标签（仅 HOUSE，如「已确认」「配房中」） | +| `progressDesc` | String | 配房进度文字（仅 HOUSE，如「已配 3 / 共 5 晚」，可空） | +| `pendingReply` | Boolean | 待回复标记（本会话有未读即 true） | + +### 3.3 请求/响应示例 + +```bash +# 待回复 tab +curl -s "https://api.test.1814.love:9443/admin/message/chat/conversations?onlyPending=true&pageNo=1&pageSize=20" \ + -H "Authorization: Bearer " +``` + +```json +{ + "code": 200, + "data": { + "total": 1, + "records": [ + { + "conversationKey": "HOUSE:2067442772171767810:101:205", + "bizModule": "HOUSE", + "bizId": 2067442772171767810, + "peerAdminId": 205, + "peerName": "房务·小呼", + "peerRole": "HOUSE_KEEPER", + "peerAvatar": "https://cdn.x/lin.png", + "orderNo": "HL20260618110222315", + "customerName": "韩頔", + "destination": "大理-丽江-香格里拉", + "tripDays": 7, + "bizStatusLabel": "配房中", + "progressDesc": "已配 3 / 共 5 晚", + "unreadCount": 2, + "pendingReply": true, + "lastMessagePreview": "房型需求我已收到，正在比选合适的酒店…", + "lastMessageAt": "2026-06-19 09:24:00", + "status": "ACTIVE" + } + ] + } +} +``` + +> 说明：头像由 user-service 本地解析（AdminUser 自定义头像 + 企微头像回退）；订单维度字段对 HOUSE 会话按 bizId（订单 id）批量经 Feign 取 order-v3，软依赖（order-v3 不可达则订单字段留空、列表不阻断）。 + +--- + +## 4. 收件箱 `GET /admin/message/list` 新增字段 + +| 字段 | 类型 | 说明 | +|------|------|------| +| `messageType` | String | `ORDER`=订单消息 / `NORMAL`=普通消息 | +| `messageTypeLabel` | String | `订单消息` / `普通消息` | + +派生规则：`bizId` 非空 且 `bizType` 或 `categoryCode` ∈ {ORDER, HOUSE, REFUND, FLEET} → 订单消息；否则普通消息。纯出参派生，不加 DB 列。 + +--- + +## 5. 备注 + +- 前端暂不接入（backend-ahead）。FLEET 车务业务状态标签 deferred（本期 HOUSE 会话填状态，FLEET/DIRECT 留空）。 +- 测试服已部署双实例验收通过：会话列表 8 字段就位、`onlyPending` 筛选生效、收件箱 messageType 派生、order-v3 摘要端点真订单返 orderNo/联系人/状态/进度。