frontend/plans/architecture-comparison-report.md

Messages模块与PostService/Manager架构对比分析报告

一、Messages模块架构分析

1.1 架构层次结构

Messages模块采用了清晰的分层架构，各层职责明确：

┌─────────────────────────────────────────────────────────────┐
│                      表现层 (Screens)                        │
│  ChatScreen, MessageListScreen, NotificationsScreen         │
├─────────────────────────────────────────────────────────────┤
│                      Hooks层                                │
│  useDifferentialMessages, useChatScreen                     │
├─────────────────────────────────────────────────────────────┤
│                      用例层 (UseCases)                       │
│  ProcessMessageUseCase                                       │
├─────────────────────────────────────────────────────────────┤
│                      领域层 (Entities)                       │
│  Message, Conversation, GroupNotice                         │
├─────────────────────────────────────────────────────────────┤
│                      仓库层 (Repositories)                   │
│  MessageRepository, IMessageRepository                      │
├─────────────────────────────────────────────────────────────┤
│                      数据源层 (DataSources)                  │
│  SSEClient, LocalDataSource, ApiDataSource                  │
└─────────────────────────────────────────────────────────────┘

1.2 核心组件详解

1.2.1 领域实体层 (Core/Entities)

• Message.ts: 定义消息、会话、群通知等核心领域模型
• 包含工厂函数：createMessage, createConversation
• 包含业务逻辑函数：isMessageFromCurrentUser, shouldIncrementUnread, buildTextContent

1.2.2 用例层 (Core/UseCases)

• ProcessMessageUseCase: 核心业务逻辑编排器
  • 订阅SSE事件（chat, group_message, read, recall, typing, group_notice等）
  • 消息去重处理（processedMessageIds Set）
  • 已读状态保护（pendingReadMap + 版本号机制）
  • 用户信息缓存与去重请求（pendingUserRequests Map）
  • 事件发布订阅模式（subscribers Set）

1.2.3 仓库层 (Data/Repositories)

• IMessageRepository: 定义数据访问接口

  • 消息操作：getMessages, saveMessage, updateMessageStatus, markAsRead
  • 会话操作：getConversations, saveConversation, updateUnreadCount
  • 同步操作：syncMessages, getServerLastSeq

• MessageRepository: 实现接口

  • 封装SQLite数据库操作
  • 消息与CachedMessage的转换

1.2.4 映射器层 (Data/Mappers)

• MessageMapper: 数据转换
  • fromApiResponse: API响应 → 应用模型
  • fromDbRecord: 数据库记录 → 应用模型
  • toDbRecord: 应用模型 → 数据库记录
  • toApiRequest: 应用模型 → API请求
  • 创建消息片段：createTextSegment, createImageSegment

1.2.5 差异计算基础设施 (Infrastructure/Diff)

• MessageDiffCalculator: 消息列表差异计算

  • 计算added, updated, deleted, moved, unchanged
  • 变化比例检测（changeRatio > 0.5 时触发重置）
  • 增量差异计算（基于缓存）

• MessageUpdateBatcher: 批量更新处理器

  • 16ms批量间隔（约60fps）
  • 去重和合并更新
  • 100ms最大等待时间
  • 统计信息：totalBatches, totalUpdates, averageBatchSize

• types.ts: 完整的类型定义

  • MessageUpdateType枚举：ADD, UPDATE, DELETE, MOVE, BATCH_*
  • DiffResult, DiffConfig等接口

1.2.6 Hook层

• useDifferentialMessages: 差异更新Hook
  • 集成DiffCalculator和Batcher
  • 自动处理批量更新
  • 提供flush, reset, forceUpdate方法
  • 支持配置：enableDiff, enableBatching, maxMessageCount, changeRatioThreshold

1.3 数据流

SSE事件 → ProcessMessageUseCase → 事件发布 → useChatScreen → useDifferentialMessages
                                    ↓                    ↓
                              MessageRepository      差异计算 + 批量处理
                                    ↓                    ↓
                              SQLite数据库           优化后的消息列表

1.4 状态管理方式

• 发布-订阅模式：ProcessMessageUseCase作为事件中心
• 本地SQLite缓存：消息持久化存储
• 内存状态：通过Hook返回，组件直接消费
• 差异更新：通过MessageDiffCalculator + MessageUpdateBatcher减少重渲染

---

二、PostService/Manager架构分析

2.1 架构层次结构

Post模块采用了扁平化架构，Service和Manager层职责混合：

┌─────────────────────────────────────────────────────────────┐
│                      表现层 (Screens)                        │
│  HomeScreen, PostDetailScreen, CreatePostScreen              │
├─────────────────────────────────────────────────────────────┤
│                      Hooks层                                │
│  useCursorPagination (通用), usePrefetch                     │
├─────────────────────────────────────────────────────────────┤
│                      Store层 (Zustand)                      │
│  useUserStore (直接操作状态), postManager (缓存管理)         │
├─────────────────────────────────────────────────────────────┤
│                      Service层                              │
│  postService (API调用 + 状态更新)                            │
├─────────────────────────────────────────────────────────────┤
│                      数据源                                 │
│  API (直接调用)                                             │
└─────────────────────────────────────────────────────────────┘

2.2 核心组件详解

2.2.1 Service层 (Services)

• postService.ts: 帖子服务
  • CRUD操作：getPosts, getPost, createPost, updatePost, deletePost
  • 互动操作：likePost, unlikePost, favoritePost, unfavoritePost
  • 分页支持：传统分页 + 游标分页
  • 问题：直接操作useUserStore（违反分层原则）

2.2.2 Manager层 (Stores)

• postManager.ts: 帖子缓存管理器
  • 继承CacheBus（发布订阅基类）
  • 内存缓存：listCache, detailCache
  • 请求去重：pendingRequests Map
  • TTL管理：LIST_TTL=30s, DETAIL_TTL=60s
  • 后台刷新机制

2.2.3 Store层 (Zustand)

• useUserStore: 用户状态存储
  • 直接存储posts数组
  • 帖子操作副作用直接修改状态
  • 混合了用户数据和帖子数据

2.2.4 映射器层 (Data/Mappers)

• PostMapper: 数据转换
  • fromApiResponse: API响应 → 应用模型
  • fromApiResponseList: 批量转换
  • toApiRequest: 应用模型 → API请求
  • 相比MessageMapper缺少数据库记录转换方法

2.3 数据流

HomeScreen → useCursorPagination → postService.getPostsCursor
                                    ↓
                              useUserStore.setState(posts)
                                    ↓
                              PostCard组件渲染

2.4 状态管理方式

• Zustand Store：集中式状态管理
• 内存缓存：postManager提供应用级缓存
• 请求去重：dedupe方法防止重复请求
• 直接修改：postService直接调用useUserStore.setState

---

三、主要架构差异

3.1 分层复杂度

维度	Messages模块	Post模块
层次深度	6层（Entity→UseCase→Repository→Mapper→Hook→Screen）	4层（Service→Store→Hook→Screen）
用例层	独立ProcessMessageUseCase	无
仓库接口	IMessageRepository抽象接口	无
基础设施	Diff模块（Calculator + Batcher）	无

3.2 数据持久化

维度	Messages模块	Post模块
本地存储	SQLite数据库	无
缓存抽象	MessageRepository封装	postManager内存缓存
离线支持	完整	不支持

3.3 实时更新

维度	Messages模块	Post模块
推送机制	SSE实时推送	轮询/下拉刷新
事件订阅	ProcessMessageUseCase发布订阅	无
增量更新	MessageDiffCalculator	无

3.4 状态管理

维度	Messages模块	Post模块
管理方式	发布订阅 + Hook局部状态	Zustand全局Store
状态来源	useChatScreen, useDifferentialMessages	useUserStore
批量更新	MessageUpdateBatcher	无
差异检测	MessageDiffCalculator	无

3.5 依赖方向

Messages模块（正确）：

Hook → UseCase → Repository → DataSource
              ↓
         Entity（不依赖外部）

Post模块（问题）：

Service → Store（循环依赖风险）
   ↓
API直接调用

3.6 核心问题总结

#	问题	Messages	Post
1	违反分层原则	无	postService直接操作useUserStore
2	缺少UseCase层	ProcessMessageUseCase	无业务逻辑编排
3	缺少Repository抽象	IMessageRepository	无数据访问接口
4	无差异更新	useDifferentialMessages	无
5	无批量处理	MessageUpdateBatcher	无
6	无本地持久化	SQLite	无
7	无实时推送	SSE	无

---

四、对齐建议

4.1 架构重构目标

将Post模块对齐到Messages模块的架构模式：

┌─────────────────────────────────────────────────────────────┐
│                      表现层 (Screens)                        │
│  HomeScreen, PostDetailScreen                               │
├─────────────────────────────────────────────────────────────┤
│                      Hooks层                                │
│  useDifferentialPosts (新增)                                │
├─────────────────────────────────────────────────────────────┤
│                      用例层 (UseCases)                       │
│  ProcessPostUseCase (新增)                                  │
├─────────────────────────────────────────────────────────────┤
│                      领域层 (Entities)                       │
│  Post, PostComment (新增)                                   │
├─────────────────────────────────────────────────────────────┤
│                      仓库层 (Repositories)                   │
│  PostRepository, IPostRepository (新增)                     │
├─────────────────────────────────────────────────────────────┤
│                      Service层                              │
│  postService (仅保留API调用，移除状态操作)                    │
└─────────────────────────────────────────────────────────────┘

4.2 具体改造项

4.2.1 创建Post领域实体

// src/core/entities/Post.ts
export interface Post {
  id: string;
  authorId: string;
  title: string;
  content: string;
  images: string[];
  likeCount: number;
  commentCount: number;
  // ... 其他字段
}

4.2.2 创建ProcessPostUseCase

// src/core/usecases/ProcessPostUseCase.ts
class ProcessPostUseCase {
  // 帖子增删改查
  // 点赞/收藏逻辑
  // 事件发布订阅
}

4.2.3 创建IPostRepository接口

// src/data/repositories/interfaces/IPostRepository.ts
interface IPostRepository {
  getPosts(type: string, page: number, pageSize: number): Promise<Post[]>;
  savePost(post: Post): Promise<void>;
  updatePost(postId: string, updates: Partial<Post>): Promise<void>;
  // ...
}

4.2.4 创建PostRepository实现

// src/data/repositories/PostRepository.ts
// 封装SQLite操作，实现IPostRepository接口

4.2.5 创建useDifferentialPosts Hook

// src/hooks/useDifferentialPosts.ts
// 类似useDifferentialMessages，处理帖子列表差异更新

4.2.6 改造postService

• 移除对useUserStore的直接依赖
• 仅保留API调用职责

---

五、架构对比图

graph TB
    subgraph "Messages模块 [理想架构]"
        E1[Entity<br/>Message.ts]
        U1[UseCase<br/>ProcessMessageUseCase]
        R1[Repository<br/>MessageRepository]
        M1[Mapper<br/>MessageMapper]
        H1[Hook<br/>useDifferentialMessages]
        D1[Diff基础设施<br/>DiffCalculator + Batcher]
        S1[(SQLite)]
        
        E1 --> U1
        U1 --> R1
        U1 --> D1
        R1 --> S1
        M1 --> R1
        D1 --> H1
        H1 --> S1
    end
    
    subgraph "Post模块 [当前架构]"
        E2[PostMapper]
        SV2[postService<br/>直接操作Store]
        ST2[useUserStore<br/>Zustand]
        H2[Hook<br/>useCursorPagination]
        PM2[postManager<br/>内存缓存]
        
        E2 --> SV2
        SV2 --> ST2
        H2 --> SV2
        PM2 --> ST2
    end
    
    style E1 fill:#90EE90
    style U1 fill:#90EE90
    style R1 fill:#90EE90
    style D1 fill:#90EE90
    style H1 fill:#90EE90
    style S1 fill:#90EE90
    
    style SV2 fill:#FFB6C1
    style ST2 fill:#FFB6C1

---

六、结论

Messages模块是一个架构完善的模块，具备：

1. 清晰的分层架构
2. 独立的业务逻辑编排层（UseCase）
3. 完整的数据持久化（SQLite）
4. 高效的差异更新机制
5. 实时事件推送能力

Post模块当前存在以下问题：

1. 违反分层原则：Service直接操作Store
2. 缺少UseCase层：业务逻辑分散
3. 无数据抽象：缺少Repository接口
4. 无差异更新：每次全量更新导致性能问题
5. 无本地持久化：无法离线使用

建议按照对齐建议逐步重构Post模块，使其架构与Messages模块对齐。