docs(changelog-v2): 站内信收件箱混排聊天-订单类消息恢复可见 (PR #4382)

2026-06-25 10:53:18 +08:00 · 2026-06-25 10:53:18 +08:00 · 50b65f0d41
--- a/changelogs-v2/2026-06/25_4382_站内信收件箱混排聊天-修改接口-管理后台.md
+++ b/changelogs-v2/2026-06/25_4382_站内信收件箱混排聊天-修改接口-管理后台.md
@ -0,0 +1,139 @@
+# 站内信收件箱混排聊天消息（订单类消息恢复可见）（管理后台）
+
+- **接口**：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 | 标题；聊天消息无标题（null），正文看 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）