bowong
/
expo-popcore-app
6
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
expo-popcore-app/message-adaptation-plan.md

12 KiB
Raw Blame History

消息和公告接口适配计划

日期: 2026-01-21

背景

@repo/sdk中新增了MessageController和AnnouncementController，需要适配现有的use-messages hook和创建新的use-announcements hook。

SDK接口分析

MessageController

  • list() - 获取用户消息列表（支持分页）
  • get() - 获取单条消息详情
  • markRead() - 标记消息为已读
  • batchMarkRead() - 批量标记消息为已读
  • delete() - 删除消息
  • getUnreadCount() - 获取未读消息数量

AnnouncementController

  • list() - 获取公告列表（支持分页）
  • get() - 获取单条公告详情
  • create() - 创建公告（需要权限）
  • update() - 更新公告
  • delete() - 删除公告（需要权限）
  • markRead() - 标记公告为已读
  • getUnreadCount() - 获取未读公告数量

当前问题

现有的hooks/use-messages.ts存在以下问题：

  1. 错误地使用了ChatController.chat()方法，应该使用MessageController.list()
  2. Message接口定义不完整，缺少userId、type、priority等字段
  3. ListMessagesResult缺少unreadCount字段
  4. 没有导入正确的SDK类型

适配任务

Phase 1: 修复use-messages Hook [优先级: 高] ✅ 已完成

  • 读取MessageController的类型定义
  • 从@repo/sdk导入正确的类型（Message, ListMessagesResult, MessageController）
  • 更新use-messages.ts使用MessageController.list()替代ChatController.chat()
  • 删除本地定义的Message和ListMessagesResult接口
  • 更新测试文件use-messages.test.ts以匹配新的类型
  • 运行测试确保通过（8/8测试通过）
  • 提交修复（commit: 05fb680）

完成时间: 2026-01-21 测试结果: 8 passed, 8 total 提交信息: refactor: migrate use-messages hook to MessageController with TDD

Phase 2: 创建use-announcements Hook [优先级: 高] ✅ 已完成

  • 读取AnnouncementController的类型定义
  • 创建hooks/use-announcements.ts
    • 从@repo/sdk导入Announcement, ListAnnouncementsResult, AnnouncementController
    • 参考use-templates.ts的黄金标准模式
    • 实现分页（loadMore, hasMore）
    • 实现loading和loadingMore状态
    • 实现error处理
    • 实现refetch功能
  • 创建hooks/use-announcements.test.ts（参考use-messages.test.ts）
  • 运行测试确保通过（8/8测试通过）
  • 提交新功能（commit: 21dcdc0）

完成时间: 2026-01-21 测试结果: 8 passed, 8 total 提交信息: feat: add use-announcements hook with TDD

Phase 3: 创建消息操作Hooks [优先级: 中] ✅ 已完成

  • 创建hooks/use-message-actions.ts
    • markRead(id: string) - 标记单条消息为已读
    • batchMarkRead(ids: string[]) - 批量标记消息为已读
    • deleteMessage(id: string) - 删除消息
    • 每个操作都有独立的loading和error状态
  • 创建hooks/use-message-unread-count.ts
    • 获取未读消息总数和按类型分组的未读数
    • 支持自动刷新（refetch方法）
  • 添加测试（10/10测试通过）
  • 提交新功能（commit: 83c3183）

完成时间: 2026-01-21 测试结果: 10 passed, 10 total (6 for actions + 4 for unread count) 提交信息: feat: add message action hooks with TDD

Phase 4: 创建公告操作Hooks [优先级: 中] ✅ 已完成

  • 创建hooks/use-announcement-actions.ts
    • markRead(id: string) - 标记公告为已读
    • 每个操作都有独立的loading和error状态
  • 创建hooks/use-announcement-unread-count.ts
    • 获取未读公告数量
    • 支持自动刷新（refetch方法）
  • 添加测试（8/8测试通过）
  • 提交新功能（commit: 6c17d72）

完成时间: 2026-01-21 测试结果: 8 passed, 8 total (4 for actions + 4 for unread count) 提交信息: feat: add announcement action hooks with TDD

Phase 5: UI集成 [优先级: 高] ✅ 已完成

真实使用场景：我的消息页面

  • 用户查看收到的个人消息（系统通知、活动消息、账单消息、营销消息）
  • 支持按类型筛选（全部/通知/其他）
  • 显示新消息指示点
  • 点击消息标记为已读
  • 下拉刷新获取最新消息
  • 滚动到底部加载更多历史消息

现有UI特点（保留）：

  • 三个Tab：全部(all)、通知(notice)、其他(other)
  • 消息卡片显示：标题、副标题、正文区域、时间
  • 新消息绿色指示点（右上角）
  • 空状态显示
  • 深色主题设计

已完成的适配任务：

  • 替换mock数据为useMessages hook
    • 将Tab类型映射到SDK消息类型
      • all: 所有类型
      • notice: SYSTEM + ACTIVITY
      • other: BILLING + MARKETING
    • 根据activeTab过滤消息
  • 集成UI组件
    • LoadingState: 初始加载时显示
    • ErrorState: 加载失败时显示（带重试按钮）
    • PaginationLoader: 滚动到底部时显示
    • RefreshControl: 下拉刷新功能
  • 实现消息交互
    • 点击消息卡片标记为已读
    • 已读消息隐藏绿色指示点
    • 使用useMessageActions的markRead方法
  • 数据映射
    • Message.title → cardTitle
    • Message.content → cardSubtitle
    • Message.data → cardBody（可能包含图片URL）
    • Message.createdAt → cardTime
    • !Message.isRead → 控制新消息指示点显示
  • 更新hooks/use-messages.ts支持type和isRead参数过滤
  • 提交UI集成

完成时间: 2026-01-21 提交信息: feat: integrate real message data with SDK in message page

类型定义详情

Message类型

type Message = {
  id: string;
  userId: string;
  type: MessageType; // SYSTEM | ACTIVITY | BILLING | MARKETING
  title: string;
  content: string;
  data?: any;
  link?: string;
  priority: MessagePriority; // LOW | NORMAL | HIGH | URGENT
  expiresAt?: Date;
  isRead: boolean;
  readAt?: Date;
  isDeleted: boolean;
  deletedAt?: Date;
  createdAt: Date;
  updatedAt: Date;
};

type ListMessagesResult = {
  messages: Message[];
  total: number;
  unreadCount: number;
  page: number;
  limit: number;
  totalPages: number;
};

type UnreadCountResult = {
  total: number;
  byType: {
    SYSTEM: number;
    ACTIVITY: number;
    BILLING: number;
    MARKETING: number;
  };
};

Announcement类型

type Announcement = {
  id: string;
  type: AnnouncementType;
  title: string;
  content: string;
  data?: any;
  link?: string;
  priority: MessagePriority; // LOW | NORMAL | HIGH | URGENT
  startAt: Date;
  endAt?: Date;
  isActive: boolean;
  isRead?: boolean;
  readAt?: Date;
  createdAt: Date;
  updatedAt: Date;
};

type ListAnnouncementsResult = {
  announcements: Announcement[];
  total: number;
  unreadCount: number;
  page: number;
  limit: number;
  totalPages: number;
};

type UnreadAnnouncementCountResult = {
  count: number;
};

UI适配决策

Tab类型映射

现有UI有三个Tab（all/notice/other），SDK提供四种消息类型（SYSTEM/ACTIVITY/BILLING/MARKETING）。

映射方案：

  • all: 显示所有类型的消息
  • notice: 显示 SYSTEM + ACTIVITY 类型（系统通知和活动消息）
  • other: 显示 BILLING + MARKETING 类型（账单和营销消息）

理由：

  • 保持现有UI设计不变，用户体验连续
  • notice通常指重要的系统和活动通知
  • other包含账单和营销等非紧急消息
  • 在useMessages hook中通过type参数过滤

消息卡片数据映射

UI字段 SDK字段 说明
cardTitle Message.title 消息标题
cardSubtitle Message.content 消息内容（限制2行）
cardBody Message.data 可能包含图片URL或富文本
cardTime Message.createdAt 格式化为本地时间
isNew !Message.isRead 未读消息显示绿色指示点

公告功能

暂不在message.tsx中集成公告功能，公告可能需要单独的页面或在首页展示。

决策日志

决策 理由 日期
Tab类型映射为notice/other而非直接使用SDK类型 保持现有UI设计，用户体验连续 2026-01-21
暂不集成公告功能到message.tsx 公告和消息是不同的概念，可能需要不同的展示方式 2026-01-21

项目总结

完成时间

2026-01-21

开发方法

严格遵循TDD（测试驱动开发）规范：

  • RED → Verify RED → GREEN → Verify GREEN → REFACTOR
  • 所有代码都先编写测试，确保测试失败后再实现功能
  • 每个阶段都有完整的测试覆盖

成果统计

创建的文件：

  • hooks/use-announcements.ts + 测试文件
  • hooks/use-message-actions.ts + 测试文件
  • hooks/use-message-unread-count.ts + 测试文件
  • hooks/use-announcement-actions.ts + 测试文件
  • hooks/use-announcement-unread-count.ts + 测试文件

修改的文件：

  • hooks/use-messages.ts（迁移到MessageController）
  • hooks/use-messages.test.ts（更新测试）
  • app/(tabs)/message.tsx（集成真实数据和UI组件）

测试覆盖：

  • Phase 1: 8/8 测试通过
  • Phase 2: 8/8 测试通过
  • Phase 3: 10/10 测试通过
  • Phase 4: 8/8 测试通过
  • 总计: 34/34 测试通过 (100%)

Git提交：

  • commit 05fb680: refactor: migrate use-messages hook to MessageController with TDD
  • commit 21dcdc0: feat: add use-announcements hook with TDD
  • commit 83c3183: feat: add message action hooks with TDD
  • commit 6c17d72: feat: add announcement action hooks with TDD
  • commit (最新): feat: integrate real message data with SDK in message page

功能实现

消息管理功能：

  • ✅ 消息列表获取（支持分页、过滤、排序）
  • ✅ 消息标记已读（单条/批量）
  • ✅ 消息删除
  • ✅ 未读消息计数（总数 + 按类型分组）
  • ✅ Tab切换过滤（全部/通知/其他）
  • ✅ 下拉刷新
  • ✅ 无限滚动分页加载

公告管理功能：

  • ✅ 公告列表获取（支持分页）
  • ✅ 公告标记已读
  • ✅ 未读公告计数

UI组件集成：

  • ✅ LoadingState - 初始加载状态
  • ✅ ErrorState - 错误状态（带重试）
  • ✅ PaginationLoader - 分页加载指示器
  • ✅ RefreshControl - 下拉刷新控件

技术亮点

  1. 严格的TDD流程：所有代码都经过测试驱动开发，确保质量
  2. 完整的类型安全：使用SDK提供的TypeScript类型定义
  3. 最小化代码：只实现必要的功能，避免过度工程
  4. 真实使用场景：基于实际的"我的消息"页面需求设计
  5. 良好的用户体验：加载状态、错误处理、下拉刷新、无限滚动

SDK适配完成度

✅ MessageController - 完全适配

  • list() - 消息列表
  • markRead() - 标记已读
  • batchMarkRead() - 批量标记已读
  • delete() - 删除消息
  • getUnreadCount() - 未读计数

✅ AnnouncementController - 完全适配

  • list() - 公告列表
  • markRead() - 标记已读
  • getUnreadCount() - 未读计数

后续建议

  1. 公告展示页面：创建独立的公告页面或在首页展示公告
  2. 消息推送集成：集成推送通知功能
  3. 消息搜索：添加消息搜索功能
  4. 消息分类管理：允许用户自定义消息分类
  5. 批量操作：添加批量删除、批量标记已读等功能

遇到的错误

错误 尝试 解决方案
API验证错误：type参数不接受数组 发送type: ["SYSTEM", "ACTIVITY"] 修改为单个type值，使用客户端过滤实现Tab功能

错误详情

错误信息:

{
    "code": "VALIDATION_ERROR",
    "message": "[body.type] Invalid option: expected one of \"SYSTEM\"|\"ACTIVITY\"|\"BILLING\"|\"MARKETING\""
}

原因: SDK的MessageController.list() API只接受单个MessageType值，不支持数组形式的type参数。

解决方案:

  1. 修改hooks/use-messages.ts中的type参数类型从数组改为单个值
  2. 在app/(tabs)/message.tsx中使用客户端过滤（filterMessagesByTab函数）
  3. 获取所有消息后，根据activeTab在客户端过滤显示
  4. 移除useEffect对activeTab的依赖，避免Tab切换时重新请求API

提交: fix: change type parameter from array to single value for API compatibility