📝 docs(prd): update homepage UI refactoring documentation

- add reference file paths for homepage UI refactoring story
- update task list to include component creation and TDesign integration steps
- add detailed TDesign component integration instructions
- correct story status from "Ready for Review" to "Draft"
- update change log with latest version date

📝 docs(story): revise homepage UI refactoring story details

- update acceptance criteria to align with tcb-shop-demo design
- add detailed subtasks for component implementation
- include TDesign component integration steps
- add testing requirements and verification steps
- update technical stack information and file references

docs/prd/epic-001-tcb-shop-theme-integration.md

@@ -26,6 +26,13 @@
 2. ✅ **故事2：字体系统和布局工具类集成** - 集成字体大小、字重系统和Flex布局工具类 (已完成)
 3. **故事3：图标字体和组件样式集成** - 集成图标字体系统和常用组件样式
 4. **故事4：首页UI重构** - 参照tcb-shop-demo首页设计，重构小程序首页UI
+   - **对照文件**:
+     - `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` - 商品卡片样式
 
 ## 兼容性要求
 
@@ -168,17 +175,24 @@
 ### 故事4：首页UI重构 (待开始)
 - **计划内容**: 参照tcb-shop-demo首页设计，重构小程序首页UI
 - **主要功能模块**:
-  - 搜索栏组件（带搜索图标，禁用状态）
-  - 轮播图组件（自动播放，导航指示器）
-  - 商品列表组件（商品卡片布局）
-  - 加载状态和下拉刷新
-  - 商品卡片组件（图片、标题、价格、购物车按钮）
+  - 搜索栏组件（带搜索图标，禁用状态）- 参照 `tcb-shop-demo/pages/home/home.wxml`
+  - 轮播图组件（自动播放，导航指示器）- 参照 `tcb-shop-demo/pages/home/home.wxml`
+  - 商品列表组件（商品卡片布局）- 参照 `tcb-shop-demo/components/goods-list/index.wxml`
+  - 加载状态和下拉刷新 - 参照 `tcb-shop-demo/pages/home/home.js`
+  - 商品卡片组件（图片、标题、价格、购物车按钮）- 参照 `tcb-shop-demo/components/goods-card/index.wxml`
 - **设计规范**:
-  - 渐变背景色（#fff 到 #f5f5f5）
-  - 圆角搜索框（32rpx）
-  - 商品卡片间距和布局
-  - 主色调使用（#fa550f, #fa4126）
+  - 渐变背景色（#fff 到 #f5f5f5）- 参照 `tcb-shop-demo/pages/home/home.wxss`
+  - 圆角搜索框（32rpx）- 参照 `tcb-shop-demo/pages/home/home.wxss`
+  - 商品卡片间距和布局 - 参照 `tcb-shop-demo/components/goods-card/index.wxss`
+  - 主色调使用（#fa550f, #fa4126）- 参照 `tcb-shop-demo/components/goods-card/index.wxss`
 - **技术实现**:
   - 使用TDesign MiniProgram组件
   - 集成已完成的主题变量和样式系统
-  - 保持与现有TabBarLayout的兼容性
+  - 保持与现有TabBarLayout的兼容性
+- **对照文件**:
+  - 页面结构: `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`

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

@@ -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*