Merge branch 'main' of https://git.1814.love:8443/wx/hl-api-changelog

2026-06-19 17:50:21 +08:00 · 2026-06-19 17:50:21 +08:00 · 8c8edd364b
--- a/changelogs-v2/2026-06/19_4066_站内信聊天会话列表enrich-头像订单摘要待回复tab+消息类型-管理后台.md
+++ 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 <admin-token>"
+```
+
+```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/联系人/状态/进度。