fix(message): improve message synchronization and reliability

Refactor the messaging subsystem to enhance data consistency, prevent race conditions during WebSocket reconnection, and ensure accurate unread counts.

- **WebSocket Reliability**: Implement `client_msg_id` for precise message ACK matching, preventing incorrect pending message resolution in high-frequency scenarios.
- **Sync Logic**: Update `WSMessageHandler` and `MessageManager` to use a bootstrapping state, ensuring buffered SSE events are flushed only after the initial synchronization is complete.
- **State Consistency**:
    - Introduce atomic unread count increments to prevent lost updates.
    - Implement conditional rollback for optimistic read receipts, ensuring that failed API calls do not overwrite newer, valid read states.
- **Resource Management**: Add reference counting to `useMessages` hook to prevent premature clearing of loading states during rapid conversation switching or React StrictMode double-invocations.
- **Data Integrity**: Update `UserCacheService` to re-read the latest message list before applying sender info enrichment, ensuring new messages arriving during the async process are correctly processed.

src/stores/message/MessageManager.ts

@@ -154,10 +154,10 @@ class MessageManager {
 
         useMessageStore.getState().setInitialized(true);
 
-        // 处理缓冲的 SSE 事件
-        await this.wsHandler.flushBufferedSSEEvents();
-
+        // 先关闭 bootstrap（事件流转入正常处理路径），再做尾部 flush
+        // 避免 flush 期间新到的事件被压入 buffer 后无人消费
         this.wsHandler.setBootstrapping(false);
+        await this.wsHandler.flushBufferedSSEEvents();
 
         if (useMessageStore.getState().currentConversationId) {
           await this.fetchMessages(useMessageStore.getState().currentConversationId!);

src/stores/message/hooks.ts

@@ -100,9 +100,14 @@ interface UseMessagesReturn {
  *
  * 核心修复：
  * 1. useFocusEffect：屏幕重新获得焦点时强制同步消息，解决"需要退出重进才能看到新消息"的问题
- * 2. 清理 isLoadingMessages：组件卸载时清除残留的 loading 锁，防止下次进入被阻断
+ * 2. 引用计数清理 isLoadingMessages：仅在最后一个订阅者卸载时清除 loading 锁，
+ *    避免 StrictMode 双调用或快速切换会话时，第一次 fetch 还没完成就被清锁
  * 3. 重入时 forceSync：相同 conversationId 重复进入时强制拉取最新消息
  */
+
+// 记录每个 conversationId 上的活跃订阅数，仅在归零时清锁
+const loadingLockRefCount: Map<string, number> = new Map();
+
 export function useMessages(conversationId: string | null): UseMessagesReturn {
   const normalizedConversationId = conversationId ? String(conversationId) : null;
 
@@ -128,6 +133,10 @@ export function useMessages(conversationId: string | null): UseMessagesReturn {
       return;
     }
 
+    // 引用计数 +1
+    const prevCount = loadingLockRefCount.get(normalizedConversationId) ?? 0;
+    loadingLockRefCount.set(normalizedConversationId, prevCount + 1);
+
     lastActivatedAtRef.current = Date.now();
 
     const isReentry = lastActivatedIdRef.current === normalizedConversationId;
@@ -141,11 +150,17 @@ export function useMessages(conversationId: string | null): UseMessagesReturn {
     lastActivatedIdRef.current = normalizedConversationId;
 
     return () => {
-      // 清理活动会话 + 清除残留的 loading 锁
-      if (messageManager.getActiveConversation() === normalizedConversationId) {
-        messageManager.setActiveConversation(null);
+      // 引用计数 -1，仅在最后一个订阅者卸载时清活动会话 + 清 loading 锁
+      const nextCount = (loadingLockRefCount.get(normalizedConversationId) ?? 1) - 1;
+      if (nextCount <= 0) {
+        loadingLockRefCount.delete(normalizedConversationId);
+        if (messageManager.getActiveConversation() === normalizedConversationId) {
+          messageManager.setActiveConversation(null);
+        }
+        useMessageStore.getState().setLoadingMessages(normalizedConversationId, false);
+      } else {
+        loadingLockRefCount.set(normalizedConversationId, nextCount);
       }
-      useMessageStore.getState().setLoadingMessages(normalizedConversationId, false);
     };
   }, [normalizedConversationId]);
 

src/stores/message/services/MessageSyncService.ts

@@ -197,9 +197,10 @@ export class MessageSyncService implements IMessageSyncService {
 
   /**
    * 获取会话消息（增量同步）— 去重入口
+   * key 包含 force 维度，强制刷新会跳过非强制的 in-flight 合并
    */
   async fetchMessages(conversationId: string, afterSeq?: number, force?: boolean): Promise<void> {
-    const key = `${conversationId}:${afterSeq ?? 'all'}`;
+    const key = `${conversationId}:${afterSeq ?? 'all'}:${force ? 'force' : 'normal'}`;
     const existing = this.inflightFetches.get(key);
     if (existing) return existing;
 

src/stores/message/services/ReadReceiptManager.ts

@@ -30,7 +30,7 @@ export class ReadReceiptManager implements IReadReceiptManager {
     const normalizedId = normalizeConversationId(conversationId);
     const store = useMessageStore.getState();
     const conversation = store.getConversation(normalizedId);
-    
+
     if (!conversation) {
       console.warn('[ReadReceiptManager] 会话不存在:', normalizedId);
       return;
@@ -53,6 +53,9 @@ export class ReadReceiptManager implements IReadReceiptManager {
     this.readStateVersion++;
     const currentVersion = this.readStateVersion;
 
+    // 记录本次写入的 my_last_read_seq，用于失败时条件回滚
+    const writtenReadSeq = Math.max(Number(conversation.my_last_read_seq || 0), seq);
+
     // 1. 标记此会话有进行中的已读请求
     this.pendingReadMap.set(normalizedId, {
       timestamp: Date.now(),
@@ -64,7 +67,7 @@ export class ReadReceiptManager implements IReadReceiptManager {
     const updatedConv: ConversationResponse = {
       ...conversation,
       unread_count: 0,
-      my_last_read_seq: Math.max(Number(conversation.my_last_read_seq || 0), seq),
+      my_last_read_seq: writtenReadSeq,
     };
 
     const currentUnread = store.getUnreadCount();
@@ -79,11 +82,11 @@ export class ReadReceiptManager implements IReadReceiptManager {
       await messageService.markAsRead(normalizedId, seq);
     } catch (error) {
       console.error('[ReadReceiptManager] 标记已读API失败:', error);
-      
-      // 失败时回滚状态
-      store.updateConversation(conversation);
-      store.setUnreadCount(currentUnread.total, currentUnread.system);
-      
+
+      // 条件回滚（含 totalUnreadCount）：仅在 my_last_read_seq 仍是本次写入值时回滚，
+      // 避免覆盖并发 markAsRead 已写入的更大读游标或更小未读
+      store.rollbackReadIfUnchanged(normalizedId, writtenReadSeq, prevUnreadCount);
+
       // API 失败时立即清除保护
       this.pendingReadMap.delete(normalizedId);
       return;
@@ -137,6 +140,9 @@ export class ReadReceiptManager implements IReadReceiptManager {
     });
     store.setConversationsWithUnread(newConversations, 0, currentSystem);
 
+    // 记录本次乐观写入的"目标快照"，用于失败时条件回滚
+    const optimisticSnapshot = new Map(newConversations);
+
     try {
       // 标记系统消息已读
       await messageService.markAllSystemMessagesRead();
@@ -155,8 +161,22 @@ export class ReadReceiptManager implements IReadReceiptManager {
       }
     } catch (error) {
       console.error('[ReadReceiptManager] 标记所有已读失败:', error);
-      // 回滚：恢复原始会话和未读数
-      store.setConversationsWithUnread(new Map(conversationsMap), prevTotalUnread, currentSystem);
+      // 条件回滚：仅在 conversations 的关键字段未被其他操作修改时还原，
+      // 避免覆盖期间到达的 markAsRead / WS 推送造成的新未读
+      const current = useMessageStore.getState().conversations;
+      let stillMatches = current.size === optimisticSnapshot.size;
+      if (stillMatches) {
+        for (const [id, conv] of optimisticSnapshot.entries()) {
+          const cur = current.get(id);
+          if (!cur || cur.unread_count !== conv.unread_count || cur.my_last_read_seq !== conv.my_last_read_seq) {
+            stillMatches = false;
+            break;
+          }
+        }
+      }
+      if (stillMatches) {
+        store.setConversationsWithUnread(new Map(conversationsMap), prevTotalUnread, currentSystem);
+      }
     }
   }
 

src/stores/message/services/UserCacheService.ts

@@ -6,6 +6,7 @@
 import type { MessageResponse, UserDTO } from '../../../types/dto';
 import { api } from '@/services/core';
 import { userCacheRepository } from '@/database';
+import { useMessageStore } from '../store';
 import type { IUserCacheService } from '../types';
 
 export class UserCacheService implements IUserCacheService {
@@ -61,16 +62,20 @@ export class UserCacheService implements IUserCacheService {
 
   /**
    * 批量异步填充消息的 sender 信息
-   * 填充完成后调用 notifyUpdate 更新内存并通知订阅者
+   * 注意：fetch 期间新消息可能已到达，回调内必须重读最新 messages 列表，
+   * 否则新消息的 sender 字段不会被填充。
    */
   enrichMessagesWithSenderInfo(
     conversationId: string,
-    messages: MessageResponse[],
+    _messages: MessageResponse[],
     notifyUpdate: (conversationId: string, messages: MessageResponse[]) => void
   ): void {
+    // 取一次最新列表作为本次填充目标
+    const latestMessages = useMessageStore.getState().getMessages(conversationId);
+
     // 收集所有需要查询的唯一 sender_id（排除系统用户）
     const senderIds = [...new Set(
-      messages
+      latestMessages
         .filter(m => m.sender_id && m.sender_id !== '10000' && !m.sender)
         .map(m => m.sender_id)
     )];
@@ -87,8 +92,10 @@ export class UserCacheService implements IUserCacheService {
 
         if (senderMap.size === 0) return;
 
+        // 重新读取最新消息列表（期间可能又有新消息到达）
+        const currentMessages = useMessageStore.getState().getMessages(conversationId);
         let changed = false;
-        const updated = messages.map(m => {
+        const updated = currentMessages.map(m => {
           if (!m.sender && m.sender_id && senderMap.has(m.sender_id)) {
             changed = true;
             return { ...m, sender: senderMap.get(m.sender_id) };

src/stores/message/services/WSMessageHandler.ts

@@ -212,10 +212,13 @@ export class WSMessageHandler implements IWSMessageHandler {
   /**
    * 统一同步入口 — 节流 + 去重
    * onConnect 和 sync_required 共用此入口，防止并发触发重复同步
+   * 启动阶段（isBootstrapping=true）跳过，由 MessageManager.initialize 完成后统一触发
    */
   private async triggerSync(source: string): Promise<void> {
+    if (this.isBootstrapping) return;
+
     const now = Date.now();
-    // 最小间隔节流
+    // 最小间隔节流：避免连续 sync_required 事件短时间内重复触发全量同步
     if (now - this.lastSyncTriggerAt < MIN_RECONNECT_SYNC_INTERVAL) return;
     if (this.syncInProgress) return;
 
@@ -246,14 +249,22 @@ export class WSMessageHandler implements IWSMessageHandler {
 
   /**
    * 初始化完成后，处理缓冲的 SSE 事件
+   * 每次循环：取走当前 buffer 后立即清空（避免在 fetch 期间新事件再被覆盖）
+   * 退出条件：连续一轮没有新事件，确保 flush 期间到达的事件也被消费
    */
   async flushBufferedSSEEvents(): Promise<void> {
+    let lastChatLen = -1;
+    let lastReadLen = -1;
     for (let i = 0; i < MAX_FLUSH_ITERATIONS; i++) {
-      const hasBuffered = this.bufferedChatMessages.length > 0 || this.bufferedReadReceipts.length > 0;
-      if (!hasBuffered) return;
-
       const chatEvents = this.bufferedChatMessages;
       const readEvents = this.bufferedReadReceipts;
+      // 上一轮长度未变且都已清空，说明已稳定
+      if (chatEvents.length === lastChatLen && readEvents.length === lastReadLen) {
+        return;
+      }
+      lastChatLen = chatEvents.length;
+      lastReadLen = readEvents.length;
+      // 立即清空 buffer；flush 期间新到的事件将走正常处理路径（isBootstrapping 已是 false）
       this.bufferedChatMessages = [];
       this.bufferedReadReceipts = [];
 
@@ -528,9 +539,8 @@ export class WSMessageHandler implements IWSMessageHandler {
   }
 
   private incrementSystemUnread(): void {
-    const store = useMessageStore.getState();
-    const currentUnread = store.getUnreadCount();
-    store.setUnreadCount(currentUnread.total + 1, currentUnread.system + 1);
+    // 原子递增：避免外部 read-modify-write 造成丢计数
+    useMessageStore.getState().incrementSystemUnreadAtomic();
   }
 
   private markMessageAsRecalled(conversationId: string, messageId: string): void {

src/stores/message/store.ts

@@ -88,6 +88,10 @@ export interface MessageActions {
   removeMessage: (conversationId: string, messageId: string) => void;
   patchMessages: (conversationId: string, patches: Map<string, Partial<MessageResponse>>) => void;
   setUnreadCount: (total: number, system: number) => void;
+  /**
+   * 原子递增系统未读数：避免外部 RMW 造成丢失
+   */
+  incrementSystemUnreadAtomic: () => void;
   setLastSystemMessageAt: (time: string | null) => void;
   setSSEConnected: (connected: boolean) => void;
   setCurrentConversation: (conversationId: string | null) => void;
@@ -107,6 +111,16 @@ export interface MessageActions {
   ) => void;
   incrementUnreadAtomic: (conversationId: string) => void;
 
+  /**
+   * 原子回滚乐观已读：仅在当前会话的 my_last_read_seq 仍等于 expectedReadSeq 时才回滚
+   * 避免覆盖后续并发 markAsRead 已更新的更大值
+   */
+  rollbackReadIfUnchanged: (
+    conversationId: string,
+    expectedReadSeq: number,
+    prevUnreadCount: number,
+  ) => void;
+
   // 重置
   reset: () => void;
 }
@@ -393,6 +407,13 @@ export const useMessageStore = create<MessageStore>((set, get) => ({
     set({ totalUnreadCount: total, systemUnreadCount: system });
   },
 
+  incrementSystemUnreadAtomic: () => {
+    set(state => ({
+      totalUnreadCount: state.totalUnreadCount + 1,
+      systemUnreadCount: state.systemUnreadCount + 1,
+    }));
+  },
+
   setLastSystemMessageAt: (time: string | null) => {
     set({ lastSystemMessageAt: time });
     if (time) {
@@ -506,6 +527,36 @@ export const useMessageStore = create<MessageStore>((set, get) => ({
     });
   },
 
+  rollbackReadIfUnchanged: (
+    conversationId: string,
+    expectedReadSeq: number,
+    prevUnreadCount: number,
+  ) => {
+    const normalizedId = normalizeConversationId(conversationId);
+    set(state => {
+      const conversation = state.conversations.get(normalizedId);
+      if (!conversation) return state;
+      // 仅当本地乐观已读游标仍是本次写入的值时，才回滚未读
+      // 否则说明已被更新的 markAsRead 覆盖，不应回滚
+      if (Number(conversation.my_last_read_seq || 0) !== expectedReadSeq) {
+        return state;
+      }
+      const newConversations = new Map(state.conversations);
+      newConversations.set(normalizedId, {
+        ...conversation,
+        unread_count: prevUnreadCount,
+      });
+      const conversationList = sortConversationList(newConversations);
+      // 同步回滚 totalUnreadCount：加回本次扣减的未读数
+      const unreadDelta = prevUnreadCount - (conversation.unread_count || 0);
+      return {
+        conversations: newConversations,
+        conversationList,
+        totalUnreadCount: state.totalUnreadCount + unreadDelta,
+      };
+    });
+  },
+
   // ==================== 重置 ====================
 
   reset: () => {