|
|
@@ -1,153 +1,258 @@
|
|
|
-# Story 001.004: 首页UI重构
|
|
|
+# Story 001.004: homepage-ui-refactor
|
|
|
|
|
|
## Status
|
|
|
-Ready for Review
|
|
|
+Draft
|
|
|
|
|
|
## Story
|
|
|
-**As a** 小程序用户，
|
|
|
-**I want** 看到现代化、美观的首页界面，
|
|
|
-**so that** 我可以轻松浏览商品和享受更好的购物体验
|
|
|
+**As a** 小程序用户,
|
|
|
+**I want** 看到与tcb-shop-demo设计一致的现代化首页UI,
|
|
|
+**so that** 我能获得更好的视觉体验和更直观的商品浏览体验
|
|
|
|
|
|
## Acceptance Criteria
|
|
|
-1. 首页顶部显示搜索栏，带搜索图标，处于禁用状态
|
|
|
-2. 首页包含轮播图区域，支持自动播放和导航指示器
|
|
|
-3. 首页显示商品列表，采用瀑布流布局
|
|
|
-4. 商品卡片包含商品图片、标题、价格和购物车按钮
|
|
|
-5. 页面背景使用渐变设计（#fff 到 #f5f5f5）
|
|
|
-6. 搜索框使用圆角设计（32rpx），高度64rpx
|
|
|
-7. 商品卡片间距和布局符合tcb-shop-demo设计规范
|
|
|
-8. 主色调（#fa550f, #fa4126）正确应用于搜索图标、购物车按钮和选中状态
|
|
|
-9. 页面支持加载状态和下拉刷新功能
|
|
|
-10. 与现有TabBarLayout保持兼容性
|
|
|
+1. 首页UI结构与tcb-shop-demo一致，包含搜索栏、轮播图、商品列表区域
|
|
|
+2. 样式遵循tcb-shop-demo的设计规范，包括渐变背景、圆角搜索框等
|
|
|
+3. 商品卡片布局与tcb-shop-demo一致，包含图片、标题、价格、购物车按钮
|
|
|
+4. 使用已集成的tcb-theme.css主题变量和样式系统
|
|
|
+5. 保持与现有TabBarLayout的兼容性
|
|
|
|
|
|
## Tasks / Subtasks
|
|
|
-- [x] 创建首页组件结构 (AC: 1-10)
|
|
|
- - [x] 在 `mini/src/pages/index/` 目录下重构首页组件
|
|
|
- - [x] 集成已完成的主题变量和样式系统
|
|
|
- - [x] 确保与现有TabBarLayout的兼容性
|
|
|
-- [x] 实现搜索栏组件 (AC: 1, 6)
|
|
|
- - [x] 创建搜索栏组件，带搜索图标
|
|
|
- - [x] 设置搜索框为禁用状态
|
|
|
- - [x] 应用圆角设计（32rpx）和高度（64rpx）
|
|
|
-- [x] 实现轮播图组件 (AC: 2)
|
|
|
- - [x] 集成TDesign swiper组件
|
|
|
- - [x] 配置自动播放和导航指示器
|
|
|
- - [x] 应用主题样式和圆角设计
|
|
|
-- [x] 实现商品列表组件 (AC: 3, 4, 7)
|
|
|
- - [x] 创建商品列表组件，采用瀑布流布局
|
|
|
- - [x] 实现商品卡片组件，包含图片、标题、价格、购物车按钮
|
|
|
- - [x] 应用商品卡片间距和布局规范
|
|
|
-- [x] 实现页面样式和主题集成 (AC: 5, 8)
|
|
|
- - [x] 应用渐变背景色（#fff 到 #f5f5f5）
|
|
|
- - [x] 正确应用主色调到搜索图标、购物车按钮和选中状态
|
|
|
- - [x] 集成已完成的tcb-theme.css样式系统
|
|
|
-- [x] 实现交互功能 (AC: 9)
|
|
|
- - [x] 添加加载状态指示器
|
|
|
- - [x] 实现下拉刷新功能
|
|
|
- - [x] 添加购物车按钮点击交互
|
|
|
-- [x] 创建测试页面和验证 (AC: 1-10)
|
|
|
- - [x] 创建测试页面验证所有功能
|
|
|
- - [x] 运行现有测试确保无回归
|
|
|
- - [x] 验证与现有TabBarLayout的兼容性
|
|
|
+- [ ] 创建首页组件结构 (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#L13-L19]
|
|
|
-- **前端框架**: Taro + React (小程序框架)
|
|
|
+### 技术栈信息 [Source: architecture/tech-stack.md]
|
|
|
+- **前端框架**: React 18.0.0
|
|
|
+- **小程序框架**: Taro 4.1.4
|
|
|
- **样式系统**: 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
|
|
|
+- **组件库**: TDesign原生小程序组件 (tdesign-miniprogram)
|
|
|
+- **集成方式**: Taro中使用原生小程序组件
|
|
|
|
|
|
-### 测试要求 [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，禁用状态
|
|
|
-- **轮播图**: 自动播放，圆角设计，导航指示器
|
|
|
+### 项目结构信息 [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
|
|
|
- **商品卡片**: 图片+标题+价格+购物车按钮布局
|
|
|
-- **背景**: 渐变背景 `linear-gradient(#fff, #f5f5f5)`
|
|
|
-- **主色调**: #fa550f (主要文字色), #fa4126 (按钮主色)
|
|
|
+- **主色调**: 搜索图标颜色、购物车按钮颜色、选中状态颜色使用 #fa550f 和 #fa4126
|
|
|
+
|
|
|
+### 组件依赖
|
|
|
+- **TDesign原生小程序组件**: t-search, t-swiper, t-icon, t-toast, t-tabs
|
|
|
+- **自定义组件**: goods-list, goods-card, load-more
|
|
|
+
|
|
|
+### TDesign原生小程序组件集成说明
|
|
|
+
|
|
|
+#### 1. 安装依赖
|
|
|
+```bash
|
|
|
+cd mini
|
|
|
+npm install tdesign-miniprogram
|
|
|
+```
|
|
|
+
|
|
|
+#### 2. 配置Taro项目
|
|
|
+
|
|
|
+**在 `mini/config/index.js` 中配置组件路径：**
|
|
|
+```javascript
|
|
|
+const config = {
|
|
|
+ // ... 其他配置
|
|
|
+ copy: {
|
|
|
+ patterns: [
|
|
|
+ {
|
|
|
+ from: 'node_modules/tdesign-miniprogram/miniprogram_dist/',
|
|
|
+ to: 'tdesign/',
|
|
|
+ },
|
|
|
+ ],
|
|
|
+ },
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+**在 `mini/app.config.ts` 中注册全局组件：**
|
|
|
+```typescript
|
|
|
+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. 组件使用示例
|
|
|
|
|
|
-#### 测试标准 [Source: architecture/testing-strategy.md#L35-L64]
|
|
|
-- **测试文件位置**: `mini/tests/unit/` 和 `mini/tests/integration/`
|
|
|
-- **测试命名**: `[component].test.tsx` 格式
|
|
|
+**Search组件**
|
|
|
+```tsx
|
|
|
+<t-search
|
|
|
+ placeholder="搜索商品"
|
|
|
+ disabled={false}
|
|
|
+ shape="round"
|
|
|
+ class="rounded-[32rpx] h-[64rpx]"
|
|
|
+/>
|
|
|
+```
|
|
|
+
|
|
|
+**Swiper组件**
|
|
|
+```tsx
|
|
|
+<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组件**
|
|
|
+```tsx
|
|
|
+<t-icon name="search" size="32rpx" color="#fa550f" />
|
|
|
+<t-icon name="cart" size="32rpx" color="#fa550f" />
|
|
|
+```
|
|
|
+
|
|
|
+**Toast组件**
|
|
|
+```tsx
|
|
|
+// 在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组件**
|
|
|
+```tsx
|
|
|
+<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
|
|
|
-- **覆盖率要求**: 核心组件 ≥ 80%
|
|
|
+- **测试位置**: `__tests__` 文件夹与源码并列
|
|
|
+- **覆盖率目标**: 核心业务逻辑 > 80%
|
|
|
+- **测试类型**: 单元测试、集成测试
|
|
|
|
|
|
-#### 具体测试要求
|
|
|
-- 创建首页组件的单元测试
|
|
|
-- 验证搜索栏、轮播图、商品列表组件的功能
|
|
|
-- 测试主题样式是否正确应用
|
|
|
-- 验证与现有TabBarLayout的兼容性
|
|
|
-- 确保无回归问题
|
|
|
+#### 测试要求
|
|
|
+- 为所有新组件创建单元测试
|
|
|
+- 验证组件渲染和交互功能
|
|
|
+- 测试样式类正确应用
|
|
|
+- 验证与现有布局的兼容性
|
|
|
|
|
|
## Change Log
|
|
|
| Date | Version | Description | Author |
|
|
|
|------|---------|-------------|---------|
|
|
|
-| 2025-11-19 | 1.0 | 初始故事创建 | Bob (Scrum Master) |
|
|
|
+| 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-20250929
|
|
|
+*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
|
|
|
-- ✅ 成功重构首页组件，采用现代化UI设计
|
|
|
-- ✅ 搜索栏：圆角32rpx，高度64rpx，带搜索图标，禁用状态
|
|
|
-- ✅ 轮播图：自动播放，导航指示器，圆角设计，主题样式
|
|
|
-- ✅ 商品列表：瀑布流布局，商品卡片包含图片、标题、价格、购物车按钮
|
|
|
-- ✅ 页面样式：渐变背景（#fff 到 #f5f5f5），主色调正确应用
|
|
|
-- ✅ 交互功能：加载状态，下拉刷新，购物车按钮点击
|
|
|
-- ✅ 与现有TabBarLayout保持完全兼容
|
|
|
-- ✅ 测试通过，构建成功
|
|
|
+*Notes about the completion of tasks and any issues encountered*
|
|
|
|
|
|
### 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
|
|
|
+*List all files created, modified, or affected during story implementation*
|
|
|
+
|
|
|
+## QA Results
|
|
|
+*Results from QA Agent QA review of the completed story implementation*
|
yourname