Story 001.004: homepage-ui-refactor

Status

Draft

Story

As a 小程序用户, I want 看到与tcb-shop-demo设计一致的现代化首页UI, so that 我能获得更好的视觉体验和更直观的商品浏览体验

Acceptance Criteria

首页UI结构与tcb-shop-demo一致，包含搜索栏、轮播图、商品列表区域
样式遵循tcb-shop-demo的设计规范，包括渐变背景、圆角搜索框等
商品卡片布局与tcb-shop-demo一致，包含图片、标题、价格、购物车按钮
使用已集成的tcb-theme.css主题变量和样式系统
保持与现有TabBarLayout的兼容性

Tasks / Subtasks

创建首页组件结构 (AC: 1)
- 创建 mini/src/pages/index/index.tsx 首页组件
- 参照 tcb-shop-demo/pages/home/home.wxml 实现页面结构
- 集成搜索栏组件（带搜索图标，禁用状态）
- 集成轮播图组件（自动播放，导航指示器）
- 集成商品列表组件
- 添加加载状态和下拉刷新功能
实现商品卡片组件 (AC: 3)
- 创建 mini/src/components/goods-card/index.tsx 商品卡片组件
- 参照 tcb-shop-demo/components/goods-card/index.wxml 实现商品卡片布局
- 实现图片、标题、价格、购物车按钮布局
- 应用tcb-shop-demo的商品卡片样式
实现商品列表组件 (AC: 1)
- 创建 mini/src/components/goods-list/index.tsx 商品列表组件
- 参照 tcb-shop-demo/components/goods-list/index.wxml 实现列表结构
- 实现瀑布流布局
- 集成商品卡片组件
应用tcb-shop-demo样式系统 (AC: 2, 4)
- 应用渐变背景色（#fff 到 #f5f5f5）
- 应用圆角搜索框样式（32rpx）
- 应用商品卡片间距和布局
- 应用主色调（#fa550f, #fa4126）
集成TDesign MiniProgram组件 (AC: 1, 5)
- 安装TDesign原生小程序组件库依赖
- 安装 tdesign-miniprogram
- 在 mini/package.json 中添加依赖
- 配置Taro项目支持原生小程序组件
- 在 mini/config/index.js 中配置小程序组件路径
- 在 mini/app.config.ts 中配置usingComponents
- 使用TDesign search组件实现搜索栏
- 在首页组件中使用 t-search 组件
- 配置搜索栏属性：placeholder、disabled、shape等
- 应用tcb-shop-demo的搜索栏样式（圆角32rpx，高度64rpx）
- 使用TDesign swiper组件实现轮播图
- 在首页组件中使用 t-swiper 组件
- 配置轮播图属性：autoplay、interval、indicator-dots等
- 实现轮播图数据绑定和图片展示
- 使用TDesign icon组件实现图标
- 在首页组件中使用 t-icon 组件
- 使用搜索图标、购物车图标等
- 配置图标颜色和大小匹配tcb-shop-demo设计
- 使用TDesign toast组件实现提示
- 在首页组件中使用 t-toast 组件
- 实现加载状态、成功提示、错误提示等
- 配置Toast样式和位置
- 使用TDesign tabs组件实现分类切换
- 在首页组件中使用 t-tabs 和 t-tab-panel 组件
- 配置分类数据源和切换逻辑
- 实现分类切换时的商品列表更新
测试和验证 (AC: 5)
- 创建测试页面验证所有组件功能
- 验证与现有TabBarLayout的兼容性
- 验证样式系统正确应用
- 验证响应式布局

Dev Notes

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

前端框架: React 18.0.0
小程序框架: Taro 4.1.4
样式系统: Tailwind CSS + 自定义CSS (tcb-theme.css)
组件库: TDesign原生小程序组件 (tdesign-miniprogram)
集成方式: Taro中使用原生小程序组件

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

首页位置: mini/src/pages/index/index.tsx
组件位置: mini/src/components/
样式文件: mini/src/tcb-theme.css
布局组件: mini/src/layouts/tab-bar-layout.tsx

对照文件路径

页面结构: tcb-shop-demo/pages/home/home.wxml
页面样式: tcb-shop-demo/pages/home/home.wxss
页面逻辑: tcb-shop-demo/pages/home/home.js
商品列表: tcb-shop-demo/components/goods-list/index.wxml
商品卡片: tcb-shop-demo/components/goods-card/index.wxml
商品卡片样式: tcb-shop-demo/components/goods-card/index.wxss

已集成的样式系统

主题变量: 已在 mini/src/tcb-theme.css 中完整集成
颜色系统: 语义化颜色类、层级颜色、背景色、边框色
字体系统: 完整字体大小和字重系统
布局工具类: Flex布局、间距系统、边框处理

设计规范

渐变背景: linear-gradient(#fff, #f5f5f5)
搜索框: 圆角32rpx，高度64rpx
商品卡片: 图片+标题+价格+购物车按钮布局
主色调: 搜索图标颜色、购物车按钮颜色、选中状态颜色使用 #fa550f 和 #fa4126

组件依赖

TDesign原生小程序组件: t-search, t-swiper, t-icon, t-toast, t-tabs
自定义组件: goods-list, goods-card, load-more

TDesign原生小程序组件集成说明

1. 安装依赖

cd mini
npm install tdesign-miniprogram

2. 配置Taro项目

在 mini/config/index.js 中配置组件路径：

const config = {
  // ... 其他配置
  copy: {
    patterns: [
      {
        from: 'node_modules/tdesign-miniprogram/miniprogram_dist/',
        to: 'tdesign/',
      },
    ],
  },
}

在 mini/app.config.ts 中注册全局组件：

export default defineAppConfig({
  usingComponents: {
    't-search': 'tdesign/search/index',
    't-swiper': 'tdesign/swiper/index',
    't-icon': 'tdesign/icon/index',
    't-toast': 'tdesign/toast/index',
    't-tabs': 'tdesign/tabs/index',
    't-tab-panel': 'tdesign/tabs/tab-panel/index',
  },
})

3. 组件使用示例

Search组件

<t-search
  placeholder="搜索商品"
  disabled={false}
  shape="round"
  class="rounded-[32rpx] h-[64rpx]"
/>

Swiper组件

<t-swiper
  autoplay
  interval={3000}
  indicator-dots
>
  {banners.map((banner, index) => (
    <swiper-item key={index}>
      <image src={banner.image} mode="aspectFill" />
    </swiper-item>
  ))}
</t-swiper>

Icon组件

<t-icon name="search" size="32rpx" color="#fa550f" />
<t-icon name="cart" size="32rpx" color="#fa550f" />

Toast组件

// 在TSX中需要通过ref调用
import { createSelectorQuery } from '@tarojs/taro'

const showToast = () => {
  const query = createSelectorQuery()
  query.select('#toast').node((res) => {
    const toast = res.node
    toast.show({
      message: '操作成功',
      theme: 'success',
      duration: 2000,
    })
  }).exec()
}

// 在render中
<t-toast id="toast" />

Tabs组件

<t-tabs value={activeTab} bindchange={handleTabChange}>
  {categories.map(category => (
    <t-tab-panel key={category.id} label={category.name} value={category.id}>
      <GoodsList categoryId={category.id} />
    </t-tab-panel>
  ))}
</t-tabs>

4. 样式集成

使用Tailwind CSS类名覆盖TDesign组件默认样式
应用tcb-theme.css中的主题变量
确保组件样式与tcb-shop-demo设计保持一致
注意：原生小程序组件使用 class 属性而不是 className

Testing

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

测试框架: Vitest + Testing Library
测试位置: __tests__ 文件夹与源码并列
覆盖率目标: 核心业务逻辑 > 80%
测试类型: 单元测试、集成测试

测试要求

为所有新组件创建单元测试
验证组件渲染和交互功能
测试样式类正确应用
验证与现有布局的兼容性

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

Record the specific AI agent model and version used for development

Debug Log References

Reference any debug logs or traces generated during development

Completion Notes List

Notes about the completion of tasks and any issues encountered

File List

List all files created, modified, or affected during story implementation

QA Results

Results from QA Agent QA review of the completed story implementation

001.004.homepage-ui-refactor.md 8.5 KB History Raw