✨ feat(im): 拆出私聊 / 群聊已读两个全局开关，关闭后禁用接口与所有 UI 入口（含群回执）

ImProperties.message 新增 privateReadEnabled / groupReadEnabled，前端 config.ts 同步镜像。关闭后： - 后端：read 系列接口（read / getMaxReadMessageId / getGroupReadUserIds）抛业务异常；sendGroupMessage 强制 NO_RECEIPT 忽略 receipt=true；pull 群消息跳过 Redis 已读游标读取与 readCount 补齐 - 前端：气泡已读标签 / 群回执 popover / 「发送回执消息」下拉入口 / admin 列表「状态」「回执」列与详情对应字段按开关隐藏；自动上报 / 冷启动同步对方已读位置 / WS READ & RECEIPT handler 全部按开关短路兜底，避免打到禁用接口 - 单测：补 @Spy ImProperties 修复原本就在的 NPE，加 disabled 分支断言

✨ feat(im): 拆出私聊 / 群聊已读两个全局开关，关闭后禁用接口与所有 UI 入口（含群回执）
ImProperties.message 新增 privateReadEnabled / groupReadEnabled，前端 config.ts 同步镜像。关闭后： - 后端：read 系列接口（read / getMaxReadMessageId / getGroupReadUserIds）抛业务异常；sendGroupMessage 强制 NO_RECEIPT 忽略 receipt=true；pull 群消息跳过 Redis 已读游标读取与 readCount 补齐 - 前端：气泡已读标签 / 群回执 popover / 「发送回执消息」下拉入口 / admin 列表「状态」「回执」列与详情对应字段按开关隐藏；自动上报 / 冷启动同步对方已读位置 / WS READ & RECEIPT handler 全部按开关短路兜底，避免打到禁用接口 - 单测：补 @Spy ImProperties 修复原本就在的 NPE，加 disabled 分支断言
YunaiV
1 parent 3d8b8792
Showing 6 changed files with 147 additions and 9 deletions
yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/enums/ErrorCodeConstants.java
yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/framework/config/ImProperties.java
yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/service/message/ImGroupMessageServiceImpl.java
yudao-module-im/src/main/java/cn/iocoder/yudao/module/im/service/message/ImPrivateMessageServiceImpl.java
yudao-module-im/src/test/java/cn/iocoder/yudao/module/im/service/message/ImGroupMessageServiceImplTest.java
yudao-module-im/src/test/java/cn/iocoder/yudao/module/im/service/message/ImPrivateMessageServiceImplTest.java
@@ -18,6 +18,8 @@ public interface ErrorCodeConstants {
     ErrorCode MESSAGE_RECALL_TIMEOUT = new ErrorCode(1_040_300_007, "超过 {} 分钟的消息无法撤回");
     ErrorCode MESSAGE_QUOTE_INVALID = new ErrorCode(1_040_300_008, "引用的消息不可用");
     ErrorCode MESSAGE_NOT_IN_GROUP = new ErrorCode(1_040_300_009, "消息不属于该群");
+    ErrorCode MESSAGE_PRIVATE_READ_DISABLED = new ErrorCode(1_040_300_010, "私聊已读功能已关闭");
+    ErrorCode MESSAGE_GROUP_READ_DISABLED = new ErrorCode(1_040_300_011, "群聊已读功能已关闭");
     // ========== 群 (1-040-400-000) ==========
     ErrorCode GROUP_NOT_EXISTS = new ErrorCode(1_040_400_000, "群不存在");
@@ -69,6 +69,23 @@ public class ImProperties {
     public static class Message {
         /**
+         * 是否启用私聊已读功能
+         * <p>
+         * 关闭后：private read 接口直接抛业务异常；服务端不再下发私聊 READ / RECEIPT 事件信号。
+         * 客户端侧需镜像此开关，隐藏私聊气泡的「已读 / 未读」标签
+         */
+        private boolean privateReadEnabled = true;
+
+        /**
+         * 是否启用群聊已读功能（含群消息回执）
+         * <p>
+         * 关闭后：group read 接口直接抛业务异常；服务端不再下发群 READ / RECEIPT 事件信号；
+         * 群消息回执 receiptStatus 一并停用（即使发送方传 receipt=true 也强制落 NO_RECEIPT，不再算「N 人已读」）。
+         * 客户端侧需镜像此开关，隐藏群回执 popover 与「发送回执消息」入口
+         */
+        private boolean groupReadEnabled = true;
+
+        /**
          * pull 最大拉取数量
          */
         private int maxPullSize = 1000;
@@ -2,6 +2,7 @@ package cn.iocoder.yudao.module.im.service.message;
 import cn.hutool.core.collection.CollUtil;
 import cn.hutool.core.lang.Assert;
+import cn.hutool.core.util.BooleanUtil;
 import cn.hutool.core.util.IdUtil;
 import cn.hutool.core.util.ObjUtil;
 import cn.hutool.extra.spring.SpringUtil;
@@ -105,9 +106,7 @@ public class ImGroupMessageServiceImpl implements ImGroupMessageService {
         // 2.2 构建并保存消息
         ImGroupMessageDO message = BeanUtils.toBean(reqVO, ImGroupMessageDO.class, m -> m
                 .setSenderId(senderId).setStatus(ImMessageStatusEnum.UNREAD.getStatus()).setSendTime(LocalDateTime.now())
-                .setReceiptStatus(Boolean.TRUE.equals(reqVO.getReceipt())
-                        ? ImGroupMessageReceiptStatusEnum.PENDING.getStatus()
-                        : ImGroupMessageReceiptStatusEnum.NO_RECEIPT.getStatus()));
+                .setReceiptStatus(resolveReceiptStatus(reqVO.getReceipt())));
         groupMessageMapper.insert(message);
         // 3. WebSocket 异步推送（群内可见成员 + 发送方多端同步）
@@ -137,9 +136,7 @@ public class ImGroupMessageServiceImpl implements ImGroupMessageService {
                 .setType(dto.getType()).setContent(contentString)
                 .setStatus(ImMessageStatusEnum.UNREAD.getStatus()).setSendTime(LocalDateTime.now())
                 .setAtUserIds(dto.getAtUserIds()).setReceiverUserIds(dto.getReceiverUserIds())
-                .setReceiptStatus(Boolean.TRUE.equals(dto.getReceipt())
-                        ? ImGroupMessageReceiptStatusEnum.PENDING.getStatus()
-                        : ImGroupMessageReceiptStatusEnum.NO_RECEIPT.getStatus());
+                .setReceiptStatus(resolveReceiptStatus(dto.getReceipt()));
         // 1.3 按 type.persistent 决定是否入库
         if (ImMessageTypeEnum.validate(dto.getType()).isPersistent()) {
             groupMessageMapper.insert(message);
@@ -305,6 +302,10 @@ public class ImGroupMessageServiceImpl implements ImGroupMessageService {
         if (CollUtil.isEmpty(messages)) {
             return;
         }
+        // 群已读关闭：不查 Redis 已读游标，status 保持 DB 原值（含撤回），readCount 不补齐
+        if (BooleanUtil.isFalse(imProperties.getMessage().isGroupReadEnabled())) {
+            return;
+        }
         Map<Long, Long> readMaxMessageIdsByGroup = new HashMap<>(); // 群 → 已读位置
         Map<Long, Map<Long, Long>> readPositionsByGroup = new HashMap<>(); // 群 → (用户 → 已读位置)
         Map<Long, List<ImGroupMemberDO>> membersByGroup = new HashMap<>(); // 群 → 全部成员列表
@@ -343,6 +344,10 @@ public class ImGroupMessageServiceImpl implements ImGroupMessageService {
     @Override
     public void readGroupMessages(Long userId, Long groupId, Long messageId) {
+        // 0. 全局开关校验
+        if (BooleanUtil.isFalse(imProperties.getMessage().isGroupReadEnabled())) {
+            throw exception(MESSAGE_GROUP_READ_DISABLED);
+        }
         Assert.notNull(messageId, "已读消息编号不能为空");
         // 1. 校验用户在群中（权限校验）
         groupMemberService.validateMemberInGroup(groupId, userId);
@@ -361,6 +366,10 @@ public class ImGroupMessageServiceImpl implements ImGroupMessageService {
     @Override
     public List<Long> getGroupReadUserIds(Long userId, Long groupId, Long messageId) {
+        // 0. 全局开关校验
+        if (BooleanUtil.isFalse(imProperties.getMessage().isGroupReadEnabled())) {
+            throw exception(MESSAGE_GROUP_READ_DISABLED);
+        }
         // 1.1 校验用户在群中（权限校验）
         groupMemberService.validateMemberInGroup(groupId, userId);
         // 1.2 获取消息
@@ -614,6 +623,18 @@ public class ImGroupMessageServiceImpl implements ImGroupMessageService {
     }
     /**
+     * 计算群消息回执 status：群已读关闭时强制 NO_RECEIPT，忽略发送方传入的 receipt（receipt 为 null 等价 false）
+     */
+    private Integer resolveReceiptStatus(Boolean receipt) {
+        if (BooleanUtil.isFalse(imProperties.getMessage().isGroupReadEnabled())) {
+            return ImGroupMessageReceiptStatusEnum.NO_RECEIPT.getStatus();
+        }
+        return BooleanUtil.isTrue(receipt)
+                ? ImGroupMessageReceiptStatusEnum.PENDING.getStatus()
+                : ImGroupMessageReceiptStatusEnum.NO_RECEIPT.getStatus();
+    }
+
+    /**
      * 禁言状态校验：全群禁言 → 成员禁言；群主 / 管理员豁免全群禁言
      */
     private void validateMuteStatus(ImGroupDO group, ImGroupMemberDO senderMember) {
 package cn.iocoder.yudao.module.im.service.message;
 import cn.hutool.core.lang.Assert;
+import cn.hutool.core.util.BooleanUtil;
 import cn.hutool.core.util.IdUtil;
 import cn.hutool.core.util.ObjUtil;
 import cn.iocoder.yudao.framework.common.pojo.PageResult;
@@ -210,9 +211,13 @@ public class ImPrivateMessageServiceImpl implements ImPrivateMessageService {
     @Override
     public void readPrivateMessages(Long userId, Long receiverId, Long messageId) {
+        // 1. 全局开关校验
+        if (BooleanUtil.isFalse(imProperties.getMessage().isPrivateReadEnabled())) {
+            throw exception(MESSAGE_PRIVATE_READ_DISABLED);
+        }
         Assert.notNull(messageId, "已读消息编号不能为空");
-        // 1. 一步翻转：把 (receiverId → userId) 这条会话上、id <= messageId 的未读消息全部置为已读
-        // 仅 UNREAD 行被命中，避免覆盖已撤回/已读的状态；select-then-update 拆成单条 SQL 后也消除了竞态窗口
+        // 2. 把 (receiverId → userId) 这条会话上、id <= messageId 的未读消息一步更新为已读
+        // 仅 UNREAD 行被命中，避免覆盖已撤回/已读的状态；select-then-update 合成单条 SQL 后也消除了竞态窗口
         int updated = privateMessageMapper.updateBySenderIdAndReceiverIdAndIdLeAndStatus(
                 receiverId, userId, messageId, ImMessageStatusEnum.UNREAD.getStatus(),
                 new ImPrivateMessageDO().setStatus(ImMessageStatusEnum.READ.getStatus()));
@@ -220,7 +225,7 @@ public class ImPrivateMessageServiceImpl implements ImPrivateMessageService {
             return;
         }
-        // 2. 异步发送 READ + RECEIPT 事件（已读位置以前端上报为准，与多端 / 对方 UI 显示一致）
+        // 3. 异步发送 READ + RECEIPT 事件（已读位置以前端上报为准，与多端 / 对方 UI 显示一致）
         imWebSocketService.sendPrivateMessageAsync(userId,
                 ImPrivateMessageDTO.ofRead(userId, receiverId, messageId));
         imWebSocketService.sendPrivateMessageAsync(receiverId,
@@ -229,6 +234,9 @@ public class ImPrivateMessageServiceImpl implements ImPrivateMessageService {
     @Override
     public Long getMaxReadMessageId(Long userId, Long peerId) {
+        if (BooleanUtil.isFalse(imProperties.getMessage().isPrivateReadEnabled())) {
+            throw exception(MESSAGE_PRIVATE_READ_DISABLED);
+        }
         return privateMessageMapper.selectMaxIdBySenderIdAndReceiverIdAndStatus(
                 userId, peerId, ImMessageStatusEnum.READ.getStatus());
     }
@@ -14,6 +14,7 @@ import cn.iocoder.yudao.module.im.dal.redis.message.GroupMessageReadRedisDAO;
 import cn.iocoder.yudao.module.im.enums.message.ImGroupMessageReceiptStatusEnum;
 import cn.iocoder.yudao.module.im.enums.message.ImMessageStatusEnum;
 import cn.iocoder.yudao.module.im.enums.message.ImMessageTypeEnum;
+import cn.iocoder.yudao.module.im.framework.config.ImProperties;
 import cn.iocoder.yudao.module.im.service.group.ImGroupMemberService;
 import cn.iocoder.yudao.module.im.service.group.ImGroupService;
 import cn.iocoder.yudao.module.im.service.message.dto.ImGroupMessageSendDTO;
@@ -26,6 +27,7 @@ import org.mockito.ArgumentCaptor;
 import org.mockito.InjectMocks;
 import org.mockito.Mock;
 import org.mockito.MockedStatic;
+import org.mockito.Spy;
 import java.time.LocalDateTime;
 import java.util.*;
@@ -58,6 +60,10 @@ public class ImGroupMessageServiceImplTest extends BaseMockitoUnitTest {
     @Mock
     private ImWebSocketService imWebSocketService;
+    /** 用真实实例避免 NPE；默认值与生产保持一致（recallTimeoutMinutes=5、private/group read enabled=true、maxPullSize=1000）；个别用例可改字段测分支 */
+    @Spy
+    private ImProperties imProperties = new ImProperties();
+
     private ImGroupMessageSendReqVO buildSendReqVO() {
         ImGroupMessageSendReqVO reqVO = new ImGroupMessageSendReqVO();
         reqVO.setClientMessageId("test-uuid-group-001");
@@ -812,6 +818,58 @@ public class ImGroupMessageServiceImplTest extends BaseMockitoUnitTest {
     }
     @Test
+    public void testReadGroupMessages_disabled() {
+        // 准备：关闭群聊已读
+        imProperties.getMessage().setGroupReadEnabled(false);
+
+        // 调用并断言
+        ServiceException exception = assertThrows(ServiceException.class,
+                () -> groupMessageService.readGroupMessages(1L, 10L, 100L));
+        assertEquals(MESSAGE_GROUP_READ_DISABLED.getCode(), exception.getCode());
+        // 断言：Redis 不写、不推送
+        verify(groupMessageReadRedisDAO, never()).updateReadMaxMessageId(anyLong(), anyLong(), anyLong());
+        verify(imWebSocketService, never()).sendGroupMessageAsync(anyLong(), any(ImGroupMessageDTO.class));
+    }
+
+    @Test
+    public void testGetGroupReadUserIds_disabled() {
+        // 准备：关闭群聊已读
+        imProperties.getMessage().setGroupReadEnabled(false);
+
+        // 调用并断言
+        ServiceException exception = assertThrows(ServiceException.class,
+                () -> groupMessageService.getGroupReadUserIds(1L, 10L, 100L));
+        assertEquals(MESSAGE_GROUP_READ_DISABLED.getCode(), exception.getCode());
+    }
+
+    @Test
+    public void testSendGroupMessage_groupReadDisabled_forcesNoReceipt() {
+        // 关闭群已读：发送方传 receipt=true 也强制落 NO_RECEIPT
+        imProperties.getMessage().setGroupReadEnabled(false);
+        try (MockedStatic<SpringUtil> springUtilMockedStatic = mockStatic(SpringUtil.class)) {
+            springUtilMockedStatic.when(() -> SpringUtil.getBean(eq(ImGroupMessageServiceImpl.class)))
+                    .thenReturn(groupMessageService);
+
+            ImGroupMessageSendReqVO reqVO = buildSendReqVO();
+            reqVO.setReceipt(true); // 发送方明确要求回执
+            when(groupMessageMapper.selectBySenderIdAndClientMessageId(1L, "test-uuid-group-001"))
+                    .thenReturn(null);
+            ImGroupDO group = new ImGroupDO();
+            group.setId(10L);
+            when(groupService.validateGroupExists(10L)).thenReturn(group);
+            ImGroupMemberDO member = ImGroupMemberDO.builder()
+                    .groupId(10L).userId(1L).status(CommonStatusEnum.ENABLE.getStatus()).build();
+            when(groupMemberService.validateMemberInGroup(10L, 1L)).thenReturn(member);
+            when(groupMemberService.getActiveGroupMemberUserIdsByGroupId(10L)).thenReturn(List.of(1L, 2L));
+
+            ImGroupMessageDO result = groupMessageService.sendGroupMessage(1L, reqVO);
+
+            assertEquals(ImGroupMessageReceiptStatusEnum.NO_RECEIPT.getStatus(), result.getReceiptStatus(),
+                    "群已读关闭时即使发送方传 receipt=true 也强制落 NO_RECEIPT");
+        }
+    }
+
+    @Test
     public void testReadGroupMessages_cursorAlreadyAhead() {
         // 准备：已读游标已 >= 目标，直接返回
         ImGroupMemberDO member = ImGroupMemberDO.builder()
@@ -9,6 +9,7 @@ import cn.iocoder.yudao.module.im.dal.mysql.message.ImPrivateMessageMapper;
 import cn.iocoder.yudao.module.im.enums.friend.ImFriendStateEnum;
 import cn.iocoder.yudao.module.im.enums.message.ImMessageStatusEnum;
 import cn.iocoder.yudao.module.im.enums.message.ImMessageTypeEnum;
+import cn.iocoder.yudao.module.im.framework.config.ImProperties;
 import cn.iocoder.yudao.module.im.service.friend.ImFriendService;
 import cn.iocoder.yudao.module.im.service.sensitiveword.ImSensitiveWordService;
 import cn.iocoder.yudao.module.im.service.message.dto.ImPrivateMessageSendDTO;
@@ -19,6 +20,7 @@ import org.junit.jupiter.api.Test;
 import org.mockito.ArgumentCaptor;
 import org.mockito.InjectMocks;
 import org.mockito.Mock;
+import org.mockito.Spy;
 import java.time.LocalDateTime;
 import java.util.List;
@@ -47,6 +49,10 @@ public class ImPrivateMessageServiceImplTest extends BaseMockitoUnitTest {
     @Mock
     private ImWebSocketService imWebSocketService;
+    /** 用真实实例避免 NPE；默认值与生产保持一致（recallTimeoutMinutes=5、private/group read enabled=true）；个别用例可改字段测分支 */
+    @Spy
+    private ImProperties imProperties = new ImProperties();
+
     private ImPrivateMessageSendReqVO buildSendReqVO() {
         ImPrivateMessageSendReqVO reqVO = new ImPrivateMessageSendReqVO();
         reqVO.setClientMessageId("test-uuid-001");
@@ -294,6 +300,21 @@ public class ImPrivateMessageServiceImplTest extends BaseMockitoUnitTest {
     }
     @Test
+    public void testReadMessages_disabled() {
+        // 准备：关闭私聊已读
+        imProperties.getMessage().setPrivateReadEnabled(false);
+
+        // 调用并断言
+        ServiceException exception = assertThrows(ServiceException.class,
+                () -> privateMessageService.readPrivateMessages(1L, 2L, 5L));
+        assertEquals(MESSAGE_PRIVATE_READ_DISABLED.getCode(), exception.getCode());
+        // 断言：不更新消息状态、不推送
+        verify(privateMessageMapper, never()).updateBySenderIdAndReceiverIdAndIdLeAndStatus(
+                anyLong(), anyLong(), anyLong(), anyInt(), any(ImPrivateMessageDO.class));
+        verify(imWebSocketService, never()).sendPrivateMessageAsync(anyLong(), any(ImPrivateMessageDTO.class));
+    }
+
+    @Test
     public void testReadMessages_noUnread() {
         // 准备：mapper 返回 0 表示 id <= messageId 范围内没有未读消息
         when(privateMessageMapper.updateBySenderIdAndReceiverIdAndIdLeAndStatus(
@@ -336,6 +357,17 @@ public class ImPrivateMessageServiceImplTest extends BaseMockitoUnitTest {
         assertNull(result);
     }
+    @Test
+    public void testGetMaxReadMessageId_disabled() {
+        // 准备：关闭私聊已读
+        imProperties.getMessage().setPrivateReadEnabled(false);
+
+        // 调用并断言
+        ServiceException exception = assertThrows(ServiceException.class,
+                () -> privateMessageService.getMaxReadMessageId(1L, 2L));
+        assertEquals(MESSAGE_PRIVATE_READ_DISABLED.getCode(), exception.getCode());
+    }
+
     // ========== sendPrivateMessage(senderId, dto)：helper 行为 ==========
     @Test