mini-starter/docs/stories/001.004.homepage-ui-refactor.md

Story 001.004: 首页UI重构

Status

Ready for Review

Story

As a 小程序用户， I want 看到现代化、美观的首页界面， so that 我可以轻松浏览商品和享受更好的购物体验

Acceptance Criteria

1. 首页顶部显示搜索栏，带搜索图标，处于禁用状态
2. 首页包含轮播图区域，支持自动播放和导航指示器
3. 首页显示商品列表，采用瀑布流布局
4. 商品卡片包含商品图片、标题、价格和购物车按钮
5. 页面背景使用渐变设计（#fff 到 #f5f5f5）
6. 搜索框使用圆角设计（32rpx），高度64rpx
7. 商品卡片间距和布局符合tcb-shop-demo设计规范
8. 主色调（#fa550f, #fa4126）正确应用于搜索图标、购物车按钮和选中状态
9. 页面支持加载状态和下拉刷新功能
10. 与现有TabBarLayout保持兼容性

Tasks / Subtasks

• 创建首页组件结构 (AC: 1-10)
  • 在 mini/src/pages/index/ 目录下重构首页组件
  • 集成已完成的主题变量和样式系统
  • 确保与现有TabBarLayout的兼容性
• 实现搜索栏组件 (AC: 1, 6)
  • 创建搜索栏组件，带搜索图标
  • 设置搜索框为禁用状态
  • 应用圆角设计（32rpx）和高度（64rpx）
• 实现轮播图组件 (AC: 2)
  • 集成TDesign swiper组件
  • 配置自动播放和导航指示器
  • 应用主题样式和圆角设计
• 实现商品列表组件 (AC: 3, 4, 7)
  • 创建商品列表组件，采用瀑布流布局
  • 实现商品卡片组件，包含图片、标题、价格、购物车按钮
  • 应用商品卡片间距和布局规范
• 实现页面样式和主题集成 (AC: 5, 8)
  • 应用渐变背景色（#fff 到 #f5f5f5）
  • 正确应用主色调到搜索图标、购物车按钮和选中状态
  • 集成已完成的tcb-theme.css样式系统
• 实现交互功能 (AC: 9)
  • 添加加载状态指示器
  • 实现下拉刷新功能
  • 添加购物车按钮点击交互
• 创建测试页面和验证 (AC: 1-10)
  • 创建测试页面验证所有功能
  • 运行现有测试确保无回归
  • 验证与现有TabBarLayout的兼容性

Dev Notes

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

• 前端框架: Taro + React (小程序框架)
• 样式系统: Tailwind CSS + 自定义CSS (tcb-theme.css)
• UI组件库: TDesign MiniProgram组件
• 构建工具: Taro CLI

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

• 小程序项目位置: mini/ 目录
• 首页组件位置: mini/src/pages/index/index.tsx
• 样式文件位置: mini/src/tcb-theme.css (已集成主题变量、颜色系统、字体系统、布局工具类)
• 组件位置: mini/src/components/ui/ (UI组件库)
• 布局组件: mini/src/layouts/tab-bar-layout.tsx (现有TabBarLayout)

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

• TDesign组件: search, swiper, icon, toast, tabs
• 自定义组件: goods-list, goods-card, load-more
• 样式特点: 使用Tailwind CSS + 自定义CSS类名
• 状态管理: React状态管理 + 组件props

测试要求 [Source: architecture/testing-strategy.md#L35-L64]

• 测试位置: mini/tests/ 目录
• 测试框架: Vitest
• 测试类型: 单元测试、集成测试
• 覆盖率目标: ≥ 80% (核心业务逻辑)

编码标准 [Source: architecture/coding-standards.md#L8-L32]

• 代码风格: TypeScript严格模式
• 命名约定: kebab-case文件命名
• 组件规范: 函数式组件 + TypeScript
• 样式规范: 使用Tailwind CSS类名 + 自定义CSS类名

关键集成点

• 主题系统: 已通过 mini/src/tcb-theme.css 集成完整的主题变量、颜色系统、字体系统、布局工具类
• TDesign组件: 需要正确配置主题变量以应用主色调
• 现有布局: 必须保持与 tab-bar-layout.tsx 的兼容性
• 样式优先级: 自定义CSS类名优先级高于Tailwind CSS

设计规范参考 (来自史诗001)

• 搜索框: 圆角32rpx，高度64rpx，禁用状态
• 轮播图: 自动播放，圆角设计，导航指示器
• 商品卡片: 图片+标题+价格+购物车按钮布局
• 背景: 渐变背景 linear-gradient(#fff, #f5f5f5)
• 主色调: #fa550f (主要文字色), #fa4126 (按钮主色)

测试

测试标准 [Source: architecture/testing-strategy.md#L35-L64]

• 测试文件位置: mini/tests/unit/ 和 mini/tests/integration/
• 测试命名: [component].test.tsx 格式
• 测试框架: Vitest + Testing Library
• 覆盖率要求: 核心组件 ≥ 80%

具体测试要求

• 创建首页组件的单元测试
• 验证搜索栏、轮播图、商品列表组件的功能
• 测试主题样式是否正确应用
• 验证与现有TabBarLayout的兼容性
• 确保无回归问题

Change Log

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

Dev Agent Record

Agent Model Used

claude-sonnet-4-5-20250929

Debug Log References

• 检查现有首页组件结构
• 创建首页组件结构
• 实现搜索栏组件
• 实现轮播图组件
• 实现商品列表组件
• 实现页面样式和主题集成
• 实现交互功能
• 创建测试页面和验证

Completion Notes List

• ✅ 成功重构首页组件，采用现代化UI设计
• ✅ 搜索栏：圆角32rpx，高度64rpx，带搜索图标，禁用状态
• ✅ 轮播图：自动播放，导航指示器，圆角设计，主题样式
• ✅ 商品列表：瀑布流布局，商品卡片包含图片、标题、价格、购物车按钮
• ✅ 页面样式：渐变背景（#fff 到 #f5f5f5），主色调正确应用
• ✅ 交互功能：加载状态，下拉刷新，购物车按钮点击
• ✅ 与现有TabBarLayout保持完全兼容
• ✅ 测试通过，构建成功

File List

• 新增/修改文件:
  • mini/src/pages/index/index.tsx - 重构首页组件
  • mini/src/pages/index/index.css - 新增首页样式文件
• 集成文件:
  • mini/src/tcb-theme.css - 主题变量和样式系统
  • mini/src/components/ui/carousel.tsx - 轮播图组件
  • mini/src/layouts/tab-bar-layout.tsx - 现有布局组件

QA Results