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

Status

Ready for Review

Story

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

Acceptance Criteria

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

Tasks / Subtasks

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

图片文件信息:

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 - 已集成advertisementClient
mini/src/pages/index/index.tsx - 已集成广告API调用
mini/src/components/ui/carousel.tsx - 轮播图组件

QA Results

Results from QA Agent QA review of the completed story implementation

001.006.home-banner-advertisements.md 5.9 KB Historie Surový