mini-starter/docs/stories/001.005.home-goods-data-fetching.md

Story 001.005: 首页商品列表数据读取

Status

Draft

Story

As a 小程序用户， I want 在首页看到真实的商品数据而不是模拟数据， so that 我可以浏览和购买真实的商品

Acceptance Criteria

1. 首页商品列表使用真实API数据替换模拟数据
2. 实现分页和加载更多功能
3. 保持现有UI结构和事件处理逻辑不变
4. 添加加载状态和错误处理
5. 实现触底加载更多功能
6. 保持与现有GoodsData接口兼容性

Tasks / Subtasks

• 在首页组件中集成goodsClient API调用 (AC: 1)
  • 使用useInfiniteQuery实现分页数据获取
  • 配置查询参数：page=1, pageSize=10, filters={state: 1}
  • 实现getNextPageParam逻辑
• 数据转换和兼容性处理 (AC: 1, 6)
  • 将API返回的商品数据转换为GoodsData接口格式
  • 保持现有事件处理函数签名不变
• 状态管理和错误处理 (AC: 4)
  • 添加加载状态显示
  • 实现错误状态处理
  • 添加空数据状态显示
• 触底加载更多功能 (AC: 2, 5)
  • 实现ScrollView的onScrollToLower事件处理
  • 添加加载更多状态显示
  • 实现无更多数据状态显示
• 测试和验证 (AC: 1-6)
  • 验证数据正确显示
  • 测试分页功能
  • 验证事件处理逻辑
  • 测试错误处理场景

Dev Notes

技术栈信息 [Source: architecture/tech-stack.md]

• 前端框架: React 19.1.0 + TypeScript
• 状态管理: @tanstack/react-query 5.83.0 (服务端状态管理)
• HTTP客户端: 基于Hono Client的封装
• 构建工具: Vite 7.0.0

组件架构信息 [Source: architecture/component-architecture.md]

• 前端组件架构: 基于Taro框架的小程序项目
• 组件组织: 页面组件位于 mini/src/pages/
• 共享组件: UI组件位于 mini/src/components/ui/

项目结构信息 [Source: architecture/source-tree.md]

• 目标文件: mini/src/pages/index/index.tsx
• 参考实现: mini/src/pages/goods-list/index.tsx
• API客户端: mini/src/api.ts 中的 goodsClient
• 商品组件: mini/src/components/goods-list/ 和 mini/src/components/goods-card/

数据模型信息 [Source: architecture/data-model-schema-changes.md]

• 分页响应接口:

  interface PaginatedResponse<T> {
  data: T[];
  pagination: {
    total: number;
    current: number;
    pageSize: number;
    totalPages: number;
  };
  }
  

现有实现分析

• 当前首页: 使用模拟数据 mockGoodsList
• 商品列表页面: 已实现完整的分页数据获取逻辑

• GoodsData接口:

  interface GoodsData {
  id: string;
  name?: string;
  cover_image?: string;
  price?: number;
  originPrice?: number;
  tags?: string[];
  }
  

API集成信息

• 商品API客户端: goodsClient
• 查询方法: goodsClient.$get()
• 查询参数:
  • page: 页码
  • pageSize: 每页数量
  • keyword: 搜索关键词
  • filters: JSON字符串格式的过滤条件

兼容性要求

• 保持现有 GoodsData 接口不变
• 保持现有事件处理函数签名不变
• 保持现有UI结构和样式不变

测试

测试标准 [Source: architecture/coding-standards.md]

• 测试框架: Vitest + Testing Library
• 测试位置: __tests__ 文件夹与源码并列
• 测试类型: 单元测试、集成测试

特定测试要求

• 验证数据获取和转换逻辑
• 测试分页和加载更多功能
• 验证错误处理场景
• 确保与现有组件兼容性

Change Log

Date	Version	Description	Author
2025-11-20	1.0	初始故事创建	Bob (Scrum Master)

Dev Agent Record

This section is populated by the development agent during implementation

Agent Model Used

Debug Log References

Completion Notes List

File List

QA Results

Results from QA Agent QA review of the completed story implementation