# 站内信聊天会话列表 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/联系人/状态/进度。