# Story 001.006: 首页轮播图改为后台广告图

## Status
Ready for Review

## Story
**As a** 小程序用户，
**I want** 在首页看到后台配置的广告轮播图而不是固定图片，
**so that** 我可以看到最新的推广内容和活动信息

## Acceptance Criteria
1. 首页轮播图使用后台广告数据替换模拟数据
2. 广告数据需要过滤启用的广告（status=1）
3. 轮播图样式调整为：高度为图片高度，宽度自适应且居中
4. 保持现有轮播图功能（自动播放、指示器等）
5. 添加加载状态和错误处理
6. 在API客户端中添加advertisementClient

## Tasks / Subtasks
- [x] 在API客户端中添加advertisementClient (AC: 6)
  - [x] 在 `mini/src/api.ts` 中添加 `AdvertisementRoutes` 导入
  - [x] 创建 `advertisementClient` 导出
- [x] 在首页组件中集成广告API调用 (AC: 1, 2)
  - [x] 使用 `useQuery` 获取广告数据
  - [x] 配置查询参数：过滤status=1的广告
  - [x] 配置查询参数：过滤typeId=1的广告（首页轮播广告类型）
  - [x] 按sort字段排序广告数据
- [x] 数据转换和图片URL提取 (AC: 1)
  - [x] 从广告数据中提取图片URL（imageFile.fullUrl）
  - [x] 过滤掉没有图片的广告
- [x] 样式调整和布局优化 (AC: 3)
  - [x] 保持轮播图固定高度设置（当前为300rpx）
  - [x] 设置图片填充模式为aspectFill
  - [x] 确保轮播图在容器中居中显示
- [x] 状态管理和错误处理 (AC: 5)
  - [x] 添加广告数据加载状态显示
  - [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/`
- **轮播图组件**: TDesign Swiper组件，位于 `mini/src/components/tdesign/swiper`

### 项目结构信息 [Source: architecture/source-tree.md]
- **目标文件**: `mini/src/pages/index/index.tsx`
- **API客户端**: `mini/src/api.ts`
- **广告模块**: `packages/advertisements-module/`
- **广告路由**: `packages/advertisements-module/src/routes/advertisements.ts`

### 广告数据模型信息 [Source: packages/advertisements-module/src/entities/advertisement.entity.ts]
- **广告实体字段**:
  - `id`: number - 广告ID
  - `title`: string | null - 标题
  - `code`: string | null - 调用别名
  - `url`: string | null - 跳转URL
  - `imageFileId`: number | null - 图片文件ID
  - `imageFile`: File | null - 图片文件信息
  - `sort`: number - 排序值
  - `status`: number - 状态（0禁用，1启用）
  - `actionType`: number - 跳转类型
  - `typeId`: number - 广告类型ID（1=首页轮播广告）

### 广告Schema信息 [Source: packages/advertisements-module/src/schemas/advertisement.schema.ts]
- **图片文件信息**:
  ```typescript
  imageFile: {
    id: number;
    name: string;
    fullUrl: string; // 图片完整URL
    type: string | null;
    size: number | null;
  }
  ```

### API集成信息
- **广告API路径**: `/api/v1/advertisements`
- **广告API类型**: `AdvertisementRoutes` (已在服务器包中定义)
- **查询参数**: 支持分页、搜索、过滤
- **过滤条件**:
  - `status=1` - 只显示启用的广告
  - `typeId=1` - 只显示首页轮播广告类型

### 现有实现分析
- **当前轮播图**: 使用模拟数据 `imgSrcs`
- **当前样式**: 固定高度300rpx
- **轮播图组件**: TDesign Swiper组件，支持自动播放、指示器

### 样式调整要求
- **保持固定高度**: 保持 `height="300rpx"` 固定高度
- **图片填充模式**: 使用 `aspectFill` 模式确保图片填充整个轮播图区域
- **宽度自适应**: 轮播图宽度自适应容器
- **居中显示**: 确保轮播图在容器中居中

### 兼容性要求
- 保持现有轮播图功能不变（自动播放、指示器等）
- 保持现有页面结构和布局不变
- 保持与现有TDesign Swiper组件的兼容性

### 测试
#### 测试标准 [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 (2025-11-21)

### Debug Log References
- 故事状态检查：发现大部分功能已实现，但缺少广告状态和类型过滤

### Completion Notes List
- ✅ API客户端已集成advertisementClient
- ✅ 首页组件已集成广告API调用（使用useQuery）
- ✅ 数据转换和图片URL提取已实现
- ✅ 状态管理和错误处理已实现
- ✅ 已添加广告状态过滤（status=1）
- ✅ 已添加广告类型过滤（typeId=1）
- ✅ 已保持轮播图固定高度300rpx
- ✅ 已完成测试验证

### File List
- [mini/src/api.ts](mini/src/api.ts) - 已集成advertisementClient
- [mini/src/pages/index/index.tsx](mini/src/pages/index/index.tsx) - 已集成广告API调用
- [mini/src/components/ui/carousel.tsx](mini/src/components/ui/carousel.tsx) - 轮播图组件

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