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

## Status
Ready for Review

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

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

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

## 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]
- **分页响应接口**:
  ```typescript
  interface PaginatedResponse<T> {
    data: T[];
    pagination: {
      total: number;
      current: number;
      pageSize: number;
      totalPages: number;
    };
  }
  ```

### 现有实现分析
- **当前首页**: 使用模拟数据 `mockGoodsList`
- **商品列表页面**: 已实现完整的分页数据获取逻辑
- **GoodsData接口**:
  ```typescript
  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
- Claude Sonnet 4.5 (claude-sonnet-4-5-20250929)

### Debug Log References
- 修复了类型错误：将number类型的id转换为string类型
- 移除了未使用的useState导入

### Completion Notes List
- ✅ 成功集成了goodsClient API调用，使用useInfiniteQuery实现分页数据获取
- ✅ 实现了数据转换函数，将API返回的商品数据转换为GoodsData接口格式
- ✅ 添加了完整的加载状态、错误处理和空数据状态显示
- ✅ 实现了触底加载更多功能，包括ScrollView事件处理和状态显示
- ✅ 保持了与现有GoodsData接口和事件处理函数的兼容性
- ✅ 修复了类型错误，确保代码类型安全

### File List
- [mini/src/pages/index/index.tsx](mini/src/pages/index/index.tsx) - 主要实现文件
- [mini/src/pages/index/index.css](mini/src/pages/index/index.css) - 新增样式文件

## QA Results
*Results from QA Agent QA review of the completed story implementation*