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)
- 创建Taro React版本的TDesign组件
- 创建 mini/src/components/tdesign-search/index.tsx - Search组件
- 创建 mini/src/components/tdesign-swiper/index.tsx - Swiper组件
- 创建 mini/src/components/tdesign-icon/index.tsx - Icon组件
- 创建 mini/src/components/tdesign-toast/index.tsx - Toast组件
- 创建 mini/src/components/tdesign-tabs/index.tsx - Tabs组件
- 使用TDesign search组件实现搜索栏
- 在首页组件中导入自定义Search组件
- 配置搜索栏属性：placeholder、disabled、shape等
- 应用tcb-shop-demo的搜索栏样式（圆角32rpx，高度64rpx）
- 使用TDesign swiper组件实现轮播图
- 在首页组件中导入自定义Swiper组件
- 配置轮播图属性：autoplay、interval、indicatorDots等
- 实现轮播图数据绑定和图片展示
- 使用TDesign icon组件实现图标
- 在首页组件中导入自定义Icon组件
- 使用搜索图标、购物车图标等
- 配置图标颜色和大小匹配tcb-shop-demo设计
- 使用TDesign toast组件实现提示
- 在首页组件中导入自定义Toast组件
- 实现加载状态、成功提示、错误提示等
- 配置Toast样式和位置
- 使用TDesign tabs组件实现分类切换
- 在首页组件中导入自定义Tabs组件
- 配置分类数据源和切换逻辑
- 实现分类切换时的商品列表更新
测试和验证 (AC: 5)
- 创建测试页面验证所有组件功能
- 验证与现有TabBarLayout的兼容性
- 验证样式系统正确应用
- 验证响应式布局

Dev Notes

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

前端框架: React 18.0.0
小程序框架: Taro 4.1.4
样式系统: Tailwind CSS + 自定义CSS (tcb-theme.css)
组件库: 自定义Taro React组件 (基于TDesign设计规范)
集成方式: 直接使用Taro React组件，无需原生组件集成

项目结构信息 [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

组件依赖

自定义Taro React组件: TDesignSearch, TDesignSwiper, TDesignIcon, TDesignToast, TDesignTabs
自定义组件: goods-list, goods-card, load-more

TDesign组件转写说明

1. 组件创建策略

基于TDesign原生组件源码转写成Taro React组件
保持TDesign的设计规范和交互体验
使用React Hooks和Taro API实现功能
应用tcb-shop-demo的主题样式

2. 组件实现示例

Search组件 (mini/src/components/tdesign-search/index.tsx)

import { useState } from 'react'
import { View, Input } from '@tarojs/components'
import TDesignIcon from '../tdesign-icon'

interface SearchProps {
  placeholder?: string
  disabled?: boolean
  shape?: 'round' | 'square'
  value?: string
  onChange?: (value: string) => void
  onFocus?: () => void
  onBlur?: () => void
  onSubmit?: (value: string) => void
}

export default function TDesignSearch({
  placeholder = '搜索商品',
  disabled = false,
  shape = 'round',
  value = '',
  onChange,
  onFocus,
  onBlur,
  onSubmit
}: SearchProps) {
  const [focused, setFocused] = useState(false)

  const handleInput = (e) => {
    onChange?.(e.detail.value)
  }

  const handleFocus = () => {
    setFocused(true)
    onFocus?.()
  }

  const handleBlur = () => {
    setFocused(false)
    onBlur?.()
  }

  const handleConfirm = (e) => {
    onSubmit?.(e.detail.value)
  }

  return (
    <View className={`tdesign-search tdesign-search--${shape}`}>
      <View className={`tdesign-search__input-box ${focused ? 'tdesign-search__input-box--focused' : ''}`}>
        <TDesignIcon name="search" size="32rpx" color="#fa550f" />
        <Input
          type="text"
          placeholder={placeholder}
          disabled={disabled}
          value={value}
          onInput={handleInput}
          onFocus={handleFocus}
          onBlur={handleBlur}
          onConfirm={handleConfirm}
          className="tdesign-search__input"
        />
      </View>
    </View>
  )
}

Icon组件 (mini/src/components/tdesign-icon/index.tsx)

import { View } from '@tarojs/components'

interface IconProps {
  name: string
  size?: string
  color?: string
}

export default function TDesignIcon({ name, size = '32rpx', color = '#fa550f' }: IconProps) {
  return (
    <View
      className={`tdesign-icon tdesign-icon--${name}`}
      style={{ fontSize: size, color }}
    >
      {/* 使用Unicode或SVG图标 */}
    </View>
  )
}

Swiper组件 (mini/src/components/tdesign-swiper/index.tsx)

import { useState } from 'react'
import { Swiper, SwiperItem, Image } from '@tarojs/components'

interface SwiperProps {
  images: string[]
  autoplay?: boolean
  interval?: number
  indicatorDots?: boolean
}

export default function TDesignSwiper({
  images = [],
  autoplay = true,
  interval = 3000,
  indicatorDots = true
}: SwiperProps) {
  return (
    <Swiper
      className="tdesign-swiper"
      autoplay={autoplay}
      interval={interval}
      indicatorDots={indicatorDots}
      indicatorColor="#999"
      indicatorActiveColor="#fa550f"
    >
      {images.map((image, index) => (
        <SwiperItem key={index}>
          <Image src={image} mode="aspectFill" className="tdesign-swiper__image" />
        </SwiperItem>
      ))}
    </Swiper>
  )
}

3. 样式集成

使用Tailwind CSS类名和自定义CSS
应用tcb-theme.css中的主题变量
保持与tcb-shop-demo设计的一致性
使用标准的React 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 9.6 KB Histórico Raw