# 站内信收件箱混排聊天消息（订单类消息恢复可见）（管理后台）

- **接口**：GET /admin/message/list
- **变更类型**：修改接口（收件箱列表现在混排返回「聊天消息」+「系统通知」；出参 VO 新增 3 字段）
- **端类型**：管理后台
- **日期**：2026-06-25
- **Issue**：[#4381](https://git.1814.love:8443/wx/HL/issues/4381)
- **PR**：[#4382](https://git.1814.love:8443/wx/HL/pulls/4382)

房务/车务在「站内信」收件箱里**看不到订单类聊天消息**（聊天内容）的问题已修复。收件箱列表（GET /admin/message/list）现按设计「聊天每条都落收件箱、与通知混排」返回：系统通知（kind=NOTIFY）+ 聊天消息（kind=CHAT）按时间倒序混排。聊天消息的业务类型派生为「订单消息」（messageType=ORDER），其 content 即聊天内容。出参 VO 新增 `kind`/`senderName`/`conversationKey` 三字段，供前端区分聊天行、显示发件人、跳转会话线程。

---

## 1 背景

站内信已升级为「聊天」后端：聊天消息与系统通知共用一张收件箱（admin_message），聊天行 kind=CHAT。原实现给收件箱列表查询误加了 `kind=NOTIFY` 过滤，把聊天行从列表里抹掉，导致：

- 顶部铃铛角标（GET /admin/message/unread-count）**有未读数字**（角标统计含聊天）；
- 但点进站内信列表却**看不到聊天内容**（被 kind 过滤掉）。

本次去除该过滤，恢复混排。聊天行 bizType=HOUSE、bizId=订单ID，派生为「订单消息」，即用户口中的「订单类消息」。

---

## 2 变更清单

| # | 变更项 | 变更前 | 变更后 |
|---|--------|--------|--------|
| 1 | 收件箱列表返回内容 | 仅系统通知（kind=NOTIFY） | 系统通知 + 聊天消息（kind=CHAT）混排，createTime DESC |
| 2 | 出参 VO `kind` | 无 | 新增：NOTIFY=系统通知 / CHAT=聊天消息 |
| 3 | 出参 VO `senderName` | 无 | 新增：聊天行发件人姓名（仅 kind=CHAT 有值，通知为 null） |
| 4 | 出参 VO `conversationKey` | 无 | 新增：聊天行会话键（仅 kind=CHAT 有值，前端据此跳转会话线程，通知为 null） |
| 5 | 聊天行 messageType | （此前不返回聊天行） | ORDER（订单消息），messageTypeLabel=订单消息 |
| 6 | 顶部角标 unread-count | 含 NOTIFY+CHAT | 不变（本就含两者） |

> 接口路径 / 入参 / 鉴权不变；仅「列表返回内容」与「出参 VO 字段」变化，且 VO 为新增字段（向后兼容）。

---

## 3 出参字段（AdminMessageRespVO，本次新增 3 字段加粗）

| 字段 | 类型 | 说明 |
|------|------|------|
| messageId | string | 消息 ID（雪花，String 透传） |
| categoryCode | string | 分类编码；系统通知为 SYSTEM，**聊天消息为 null**（类型看 kind/messageType） |
| title | string | 标题。系统通知=其本身标题；**聊天消息=后端派生「【聊天】发件人（角色）」**（角色为空省略括号，如「【聊天】王骁」；PR #4386），收件箱标题列一眼可辨「谁发来的聊天」，正文仍看 content |
| content | string | 正文；聊天消息时即**聊天内容** |
| link | string | 跳转链接（通知用，聊天为 null） |
| bizId | string | 关联业务 ID；聊天消息为订单 ID |
| bizType | string | 关联业务类型；聊天消息为 HOUSE |
| isRead | int | 0 未读 / 1 已读 |
| createTime | long | 创建时间戳（ms） |
| messageType | string | ORDER=订单消息 / NORMAL=普通消息（派生）。聊天消息恒为 ORDER |
| messageTypeLabel | string | 订单消息 / 普通消息 |
| **kind** | string | **NOTIFY=系统通知 / CHAT=聊天消息**（区分行类型） |
| **senderName** | string | **发件人姓名（仅 kind=CHAT 有值；系统通知为 null）** |
| **conversationKey** | string | **会话键（仅 kind=CHAT 有值，前端据此跳转会话线程；系统通知为 null）** |

---

## 4 前端接入指引（重要）

1. **区分行类型**：用 `kind` 判断渲染样式——`NOTIFY` 走原系统通知样式（title+content+link）；`CHAT` 走聊天行样式（发件人 senderName + content=聊天内容，归类为「订单消息」）。
2. **聊天行点击 = 进会话线程**：点击 kind=CHAT 行时，用 `conversationKey` 进入会话线程（聊天线程/会话详情），由会话侧标记已读（会同步清掉该会话未读水位）。**不要对聊天行调 PUT /{id}/read 或 PUT /read-all 来标已读**。
3. **批量已读只清通知**：PUT /read-all（全部已读）、PUT /category/{code}/read（分类已读）、GET /categories（分类未读汇总）**只作用于系统通知（kind=NOTIFY），不碰聊天行**——聊天读态由会话维度权威维护（防误清未点开的聊天未读、防未读水位漂移）。所以点「全部已读」后聊天行仍可能保持未读，属预期。
4. **顶部角标**：GET /admin/message/unread-count 含 NOTIFY+CHAT 全部未读（口径与列表一致）。

---

## 5 示例

请求
```
GET /admin/message/list?pageNo=1&pageSize=20
Authorization: Bearer <token>
```

响应（节选，混排：一条聊天 + 一条通知）
```json
{
  "code": 200,
  "msg": "success",
  "data": {
    "total": 26,
    "records": [
      {
        "messageId": "20699...",
        "kind": "CHAT",
        "messageType": "ORDER",
        "messageTypeLabel": "订单消息",
        "senderName": "张三",
        "conversationKey": "HOUSE:2069593503129636865",
        "bizType": "HOUSE",
        "bizId": "2069593503129636865",
        "title": null,
        "content": "改日期走修改订单 我没有权限",
        "categoryCode": null,
        "isRead": 0,
        "createTime": 1750..."
      },
      {
        "messageId": "20698...",
        "kind": "NOTIFY",
        "messageType": "ORDER",
        "messageTypeLabel": "订单消息",
        "senderName": null,
        "conversationKey": null,
        "bizType": "HOUSE",
        "bizId": "2069...",
        "title": "房务询单已超时",
        "content": "订单 ... 的房务询单已超时未确认",
        "categoryCode": "SYSTEM",
        "isRead": 1,
        "createTime": 1750..."
      }
    ]
  }
}
```

---

## 6 影响评估 / 回滚

破坏兼容性：否（VO 为新增字段；老前端忽略新字段即可，原有字段不变）。

- 行为变化：收件箱列表会**多出聊天行**（kind=CHAT，显示为订单消息）。若前端未按 kind 区分渲染，聊天行会以「无标题、content=聊天内容」的形态出现在列表里——建议按第 4 节接入。
- 已在测试服实测：admin（adminId=1001）收件箱 26 条（21 聊天 + 5 通知）全部混排返回，与 DB 计数一致。

回滚方案：回滚后端至 #4382 前版本，收件箱恢复仅返系统通知（聊天行重新被隐藏）。

---

## 7 关联 / 联系人

- **Issue**：[#4381](https://git.1814.love:8443/wx/HL/issues/4381)
- **PR**：[#4382 站内信收件箱混排聊天——房务订单类消息恢复可见](https://git.1814.love:8443/wx/HL/pulls/4382)
- **设计依据**：站内信升级聊天 INAPP-CHAT v1.0 决策②（聊天每条都落收件箱、与通知混排）
- **后端负责人**：王骁（wx）
