diff --git a/changelogs-v2/2026-06/25_4382_站内信收件箱混排聊天-修改接口-管理后台.md b/changelogs-v2/2026-06/25_4382_站内信收件箱混排聊天-修改接口-管理后台.md new file mode 100644 index 0000000..9bc0f4e --- /dev/null +++ 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 +``` + +响应(节选,混排:一条聊天 + 一条通知) +```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)