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

史诗001：tcb-shop-demo主题样式集成 - 棕地增强

史诗目标

将tcb-shop-demo包中的主题、样式和设计规范分析并集成到当前小程序项目中，提升UI一致性和用户体验，同时保持现有系统的完整性。

当前进度

• 完成度: 100% (10/10 故事完成)
• 已集成: 主题变量、颜色系统、字体系统、布局工具类、组件样式、首页UI重构、首页商品列表数据读取、首页轮播图后台广告数据、用户中心UI重构、商品分类页基础组件开发、商品列表页UI重构
• 待完成: 无

史诗描述

现有系统上下文

• 当前相关功能：小程序使用Tailwind CSS和自定义样式，主要关注滚动条样式和基础布局
• 技术栈：小程序框架 + Tailwind CSS + 自定义CSS
• 集成点：样式文件、组件样式、主题变量

增强详情

• 添加/更改内容：集成tcb-shop-demo的完整样式系统，包括主题变量、颜色系统、字体系统、布局工具类、图标字体和组件样式
• 集成方式：将tcb-shop-demo的样式文件迁移到当前项目，保持与现有Tailwind CSS的兼容性
• 成功标准：样式系统完整集成，现有功能不受影响，UI一致性提升

故事

1. ✅ 故事1：主题变量和颜色系统集成 - 迁移tcb-shop-demo的主题变量和完整的颜色系统 (已完成)
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 - 商品卡片样式

5. ✅ 故事5：首页商品列表数据读取 - 在首页增加商品列表数据读取功能，替换模拟数据 (已完成)

   • 目标文件: mini/src/pages/index/index.tsx
   • 参考实现: mini/src/pages/goods-list/index.tsx
   • 技术要点:
     • 使用 useInfiniteQuery 支持分页和加载更多功能
     • 集成 goodsClient API 调用
     • 保持现有 GoodsData 接口兼容性
     • 添加加载状态和错误处理
     • 保持现有事件处理逻辑
     • 实现触底加载更多功能

6. ✅ 故事6：首页轮播图改为后台广告图 - 将首页轮播图改为后台广告图，样式高度为图片高度，宽度自适应且居中 (已完成)

   • 目标文件: mini/src/pages/index/index.tsx
   • 技术要点:
     • 在 mini/src/api.ts 中添加 advertisementClient
     • 使用 useQuery 获取广告数据
     • 过滤启用的广告（status=1）
     • 样式调整：高度为图片高度，宽度自适应且居中
     • 保持现有轮播图功能（自动播放、指示器等）
     • 添加加载状态和错误处理

7. ✅ 故事7：用户中心UI重构 - 参照tcb-shop-demo用户中心设计，重构小程序用户中心UI (已完成)

   • 对照文件:
     • tcb-shop-demo/pages/usercenter/index.wxml - 用户中心结构模板
     • tcb-shop-demo/pages/usercenter/index.wxss - 用户中心样式文件
     • tcb-shop-demo/pages/usercenter/index.js - 用户中心逻辑文件
   • 目标文件: mini/src/pages/profile/index.tsx
   • 技术要点:
     • 重构用户信息卡片布局，添加背景图片
     • 集成订单状态卡片（待付款、待发货、待收货、待评价）
     • 添加功能菜单（收货地址、联系客服等）
     • 应用tcb-shop-demo用户中心设计规范
     • 保持现有用户认证和头像上传功能
     • 集成客服弹窗功能

8. ✅ 故事8：商品分类页基础组件开发 - 实现商品分类页所需的4个基础组件：侧边栏、侧边栏项、标签栏、标签栏更多组件 (已完成)

   • 组件依赖：
     • 侧边栏组件：c-sidebar（滚动容器，宽度176rpx）- ✅ 已实现
     • 侧边栏项组件：c-sidebar-item（选中状态、圆角效果）- ✅ 已实现
     • 标签栏组件：c-tabbar（水平滚动，支持更多）- ✅ 已实现
     • 标签栏更多组件：c-tabbar-more（下拉面板，3列网格）- ✅ 已实现
   • 对照文件:
     • tcb-shop-demo/pages/goods/category/components/goods-category/components/c-sidebar/* - 侧边栏组件
     • tcb-shop-demo/pages/goods/category/components/goods-category/components/c-sidebar/c-sidebar-item/* - 侧边栏项组件
     • tcb-shop-demo/pages/goods/category/components/goods-category/components/c-tabbar/* - 标签栏组件
     • tcb-shop-demo/pages/goods/category/components/goods-category/components/c-tabbar/c-tabbar-more/* - 标签栏更多组件
   • 目标文件:
     • mini/src/components/category/CategorySidebar/index.tsx - 侧边栏组件
     • mini/src/components/category/CategorySidebarItem/index.tsx - 侧边栏项组件
     • mini/src/components/category/CategoryTabbar/index.tsx - 标签栏组件
     • mini/src/components/category/CategoryTabbarMore/index.tsx - 标签栏更多组件
   • 技术要点:
     • 实现侧边栏滚动容器，固定宽度176rpx - ✅ 已实现
     • 实现侧边栏项选中状态（左侧红色指示条，文字红色圆角背景）- ✅ 已实现
     • 实现标签栏水平滚动，支持超过4项时显示更多按钮 - ✅ 已实现
     • 实现标签栏更多下拉面板，3列网格布局 - ✅ 已实现
     • 应用tcb-shop-demo组件设计规范 - ✅ 已实现
     • 保持与现有TDesign组件系统的兼容性 - ✅ 已实现

9. ✅ 故事9：商品分类页开发 - 参照tcb-shop-demo商品分类页设计，在mini增加商品分类页，并作为tabbar一级页 (已完成)

10. ✅ 故事10：商品列表页UI重构 - 参照tcb-shop-demo商品列表页设计，重构小程序商品列表页UI (已完成)

    • 对照文件:
      • tcb-shop-demo/pages/goods/list/index.wxml - 商品列表页结构模板
      • tcb-shop-demo/pages/goods/list/index.wxss - 商品列表页样式文件
      • tcb-shop-demo/pages/goods/list/index.js - 商品列表页逻辑文件
    • 目标文件: mini/src/pages/goods-list/index.tsx
    • 技术要点:
      • 页面层级调整：商品列表页改为二级页面，移除TabBarLayout
      • 页面背景色：应用白色背景 #fff
      • 商品列表容器：应用灰色背景 #f2f2f2，添加内边距 20rpx 24rpx
      • 搜索栏样式：使用TDesign Search组件，圆角32rpx，高度64rpx
      • 商品列表布局：使用现有的GoodsList组件，保持flex布局
      • 页面结构：参照demo页面结构，使用相同的容器类名
      • 样式集成：应用tcb-shop-demo商品列表页设计规范
      • 功能保持：保持现有搜索、分类筛选、分页加载等功能
      • 导航栏：添加返回按钮，显示页面标题
    • 成功标准：
      • 商品列表页UI与tcb-shop-demo设计完全一致
      • 页面层级调整为二级页面，移除TabBarLayout
      • 现有功能无回归
      • 页面样式应用tcb-shop-demo设计规范
      • 组件TypeScript编译正常，无错误
      • tcb-shop-demo/pages/goods/category/components/goods-category/index.wxml - 商品分类组件结构
      • tcb-shop-demo/pages/goods/category/components/goods-category/index.wxss - 商品分类组件样式
    • 目标文件: mini/src/pages/category/index.tsx
    • 技术要点:
      • 使用故事8中实现的4个基础组件 - ✅ 所有组件已实现
      • 实现左侧边栏一级分类导航（c-sidebar组件，宽度176rpx）- ✅ 已实现
      • 实现侧边栏项组件（c-sidebar-item），支持选中状态和圆角效果 - ✅ 已实现
      • 实现右侧二级分类网格布局（3列网格，grid-template-columns: 33.33% 33.33% 33.33%）- ✅ 已实现
      • 实现标签栏组件（c-tabbar），支持水平滚动和下拉更多功能 - ✅ 已实现
      • 集成分类数据API调用（getCates服务）- ✅ 已实现
      • 支持广告图显示（固定位置：bottom: 13%; right: 3%）- ✅ 已实现
      • 点击分类跳转到商品列表页（传递cateId参数）- ✅ 已实现
      • 应用tcb-shop-demo商品分类页设计规范 - ✅ 已实现
      • 作为tabbar一级页面集成 - ✅ 已实现
      • 使用现有TDesign组件：Image、Toast - ✅ 已实现

兼容性要求

• 现有API保持不变
• 样式系统与现有Tailwind CSS兼容
• UI更改遵循现有模式
• 性能影响最小化

风险缓解

• 主要风险：样式冲突导致现有UI破坏
• 缓解措施：分阶段集成，充分测试，保持现有样式优先级
• 回滚计划：备份现有样式文件，可快速恢复

完成定义

• 所有故事完成且验收标准满足 (10/10 完成)
• 现有功能通过测试验证
• 集成点正常工作
• 文档适当更新
• 现有功能无回归

验证清单

范围验证

• 史诗可在1-3个故事内完成
• 无需架构文档
• 增强遵循现有模式
• 集成复杂度可控

风险评估

• 对现有系统风险低
• 回滚计划可行
• 测试方法覆盖现有功能
• 团队对集成点有足够了解

完整性检查

• 史诗目标清晰可实现
• 故事范围适当
• 成功标准可衡量
• 依赖项已识别

技术发现总结

tcb-shop-demo样式系统分析

1. 主题变量系统 ✅ (已完成)

• 主要主题色：#fa4126 (按钮主色), #fa550f (主要文字色)
• TDesign组件主题：自定义了TDesign MiniProgram组件的主题变量
• 按钮样式：定义了完整的按钮状态和变体
• 集成状态：已通过 mini/src/tcb-theme.css 完整集成

2. 颜色系统 ✅ (已完成)

• 语义化颜色类：.text-primary, .text-success, .text-warn, .text-danger
• 层级颜色：.text-title (#282828), .text-normal (#5d5d5d), .text-small (#9b9b9b)
• 背景色类：对应的背景色类名
• 集成状态：已通过 mini/src/tcb-theme.css 完整集成，包含语义化颜色、层级颜色、背景色、边框色、按钮样式、状态指示器等

3. 字体系统 ✅ (已完成)

• 字体大小：从20rpx到82rpx的完整字体大小系统
• 字重系统：.fw-super (800), .fw-main (600), .fw-normal (400), .fw-minor (300)
• 行高和文本截断：多行文本截断工具类
• 集成状态：已通过 mini/src/tcb-theme.css 完整集成

4. 布局工具类 ✅ (已完成)

• Flex布局：完整的Flex工具类系统
• 间距系统：基于rpx的padding和margin工具类
• 边框处理：1px边框处理方案
• 集成状态：已通过 mini/src/tcb-theme.css 完整集成

5. 图标字体系统 ✅ (已完成)

• 图标实现：使用Heroicons图标系统替代图标字体
• 图标组件：TDesign Icon组件支持自定义图标
• 集成状态：已通过TDesign组件库完整集成

6. 组件样式 ✅ (已完成)

• TDesign组件库：Search、Icon、Swiper、Toast、Tabs组件
• 商品卡片：完整的商品数据模型和事件处理
• 商品列表：flex布局，支持商品卡片集成
• 集成状态：所有组件样式已完整集成，应用tcb-shop-demo设计规范

7. 首页UI设计模式 ✅ (已完成)

• 页面结构：
  • 顶部搜索栏（禁用状态，带搜索图标）- 已实现
  • 轮播图区域（自动播放，圆角设计，aspectFill模式）- 已实现
  • 商品列表区域（flex布局）- 已实现
• 组件依赖：
  • TDesign组件：search, swiper, icon, toast, tabs - 已实现
  • 自定义组件：goods-list, goods-card - 已实现
• 样式特点：
  • 渐变背景：linear-gradient(#fff, #f5f5f5) - 已实现
  • 搜索框：圆角32rpx，高度64rpx - 已实现
  • 商品卡片：图片+标题+价格+购物车按钮布局 - 已实现
  • 主色调应用：搜索图标颜色、购物车按钮颜色、选中状态颜色 - 已实现
• 集成状态：首页UI重构已完成，与tcb-shop-demo设计完全一致

8. 用户中心UI设计模式 ✅ (已完成)

• 页面结构：
  • 顶部用户信息卡片（带背景图片）- 已实现
  • 订单状态卡片（待付款、待发货、待收货、待评价）- 已实现
  • 功能菜单区域（收货地址、联系客服等）- 已实现
• 组件依赖：
  • TDesign组件：user-center-card, order-group, cell-group, cell, icon, popup, toast - 已实现
• 样式特点：
  • 背景图片：https://we-retail-static-1300977798.cos.ap-guangzhou.myqcloud.com/retail-mp/common/user-center-bg.png - 已实现
  • 内容区域：margin-top: 340rpx - 已实现
  • 圆角设计：border-radius: 10rpx - 已实现
  • 1px边框处理：使用scale缩放方案 - 已实现
• 集成状态：用户中心UI重构已完成，与tcb-shop-demo设计完全一致

9. 商品分类页设计模式 ✅ (已完成)

• 页面结构：
  • 左侧边栏：一级分类导航（固定宽度176rpx）- ✅ 基础组件已实现
  • 右侧内容区：二级分类网格布局（3列）- ✅ 已实现
  • 广告图区域：固定位置显示广告图 - ✅ 已实现
• 组件依赖：
  • 使用故事8中实现的4个基础组件 - ✅ 所有组件已实现
  • TDesign组件：image, toast - ✅ 已实现
• 样式特点：
  • 左侧边栏背景色：#f5f5f5 - ✅ 已实现
  • 右侧内容区背景色：white - ✅ 已实现
  • 二级分类网格：grid-template-columns: 33.33% 33.33% 33.33% - ✅ 已实现
  • 分类图片尺寸：144rpx × 144rpx - ✅ 已实现
  • 广告图位置：position: fixed; bottom: 13%; right: 3% - ✅ 已实现
  • 侧边栏选中状态：左侧红色指示条，文字变为红色圆角背景 - ✅ 已实现
  • 标签栏选中状态：蓝色文字，底部边框 - ✅ 已实现
• 交互功能：
  • 点击侧边栏项切换一级分类 - ✅ 基础功能已实现
  • 点击二级分类跳转到商品列表页 - ✅ 已实现
  • 标签栏超过4项时显示更多下拉面板 - ✅ 已实现
• 集成状态：商品分类页已完成，所有基础组件已实现

集成策略

1. 分阶段集成：按故事顺序逐步集成
2. 兼容性处理：保持与Tailwind CSS的兼容性
3. 命名冲突避免：使用前缀或命名空间避免类名冲突
4. 测试验证：每个阶段进行充分测试验证

成功指标

• ✅ 所有tcb-shop-demo样式类可用
• ✅ 现有功能无回归
• ✅ UI一致性显著提升
• ✅ 开发效率提高（通过工具类复用）
• ✅ 首页商品数据真实化
• ✅ 首页轮播图使用后台广告数据
• ✅ 用户中心UI与tcb-shop-demo设计一致
• ✅ 商品分类页基础组件与tcb-shop-demo设计一致
• ✅ 商品分类页与tcb-shop-demo设计一致

故事完成状态

故事1：主题变量和颜色系统集成 ✅ (已完成)

• 完成日期: 2025-11-19
• 实施者: James (Full Stack Developer)
• 关键成果:
  • 创建了 mini/src/tcb-theme.css 文件，包含完整的主题变量和颜色系统
  • 集成了语义化颜色类（.text-primary, .text-success, .text-warn, .text-danger）
  • 集成了层级颜色类（.text-title, .text-normal, .text-small, .text-minor, .text-border）
  • 集成了TDesign组件主题变量
  • 创建了完整的测试套件 mini/tests/theme-colors.test.tsx
  • 所有测试通过，无回归问题
  • 与现有Tailwind CSS系统完全兼容

故事2：字体系统和布局工具类集成 ✅ (已完成)

• 完成日期: 2025-11-19
• 实施者: James (Full Stack Developer)
• 关键成果:
  • 扩展了 mini/src/tcb-theme.css 文件，添加了完整的字体系统和布局工具类
  • 集成了字体大小系统（20rpx到82rpx的完整类名）
  • 集成了字重系统（.fw-super, .fw-main, .fw-normal, .fw-minor）
  • 集成了Flex布局工具类（对齐、分布、方向、换行）
  • 集成了间距系统（基于rpx的padding和margin工具类）
  • 添加了边框处理工具类（1px边框处理方案）
  • 创建了测试页面 mini/src/pages/test-font-layout/ 验证所有类名可用
  • 所有测试通过，无回归问题
  • 与现有Tailwind CSS系统完全兼容

故事3：图标字体和组件样式集成 ✅ (已完成)

• 完成日期: 2025-11-20
• 实施者: James (Full Stack Developer)
• 关键成果:
  • 创建了完整的TDesign组件库（Search、Icon、Swiper、Toast、Tabs组件）
  • 实现了组件样式架构，每个组件都有独立的样式文件
  • 集成了Heroicons图标系统，替代了图标字体
  • 创建了商品卡片组件，包含完整的商品数据模型和事件处理
  • 创建了商品列表组件，支持flex布局和商品卡片集成
  • 所有组件都应用了tcb-shop-demo的设计规范
  • 组件样式与主题系统完全兼容
  • 所有组件TypeScript编译正常，无错误

故事4：首页UI重构 ✅ (已完成)

• 完成日期: 2025-11-20
• 实施者: James (Full Stack Developer)
• 关键成果:
  • 重构了 mini/src/pages/index/index.tsx 首页组件
  • 集成了TDesign Search组件（禁用状态，圆角32rpx）
  • 集成了TDesign Swiper组件（自动播放，导航指示器，aspectFill模式）
  • 集成了GoodsList商品列表组件
  • 应用了tcb-shop-demo页面结构（home-page-header + home-page-container）
  • 应用了渐变背景色（#fff 到 #f5f5f5）
  • 同步了tcb-shop-demo轮播图优化（固定高度300rpx）
  • 简化了轮播图容器样式，移除冗余flex布局
  • 修复了首页TypeScript错误（未使用变量和导入问题）
  • 更新了TDesign Swiper组件配置，设置高度为300rpx
  • 与现有TabBarLayout完全兼容
  • 首页组件TypeScript编译正常，无错误

故事5：首页商品列表数据读取 ✅ (已完成)

• 完成日期: 2025-11-20
• 实施者: James (Full Stack Developer)
• 关键成果:
  • 重构了 mini/src/pages/index/index.tsx 首页组件，使用真实API数据
  • 集成了 useInfiniteQuery 支持分页和加载更多功能
  • 实现了 goodsClient.$get() API 调用，获取真实商品数据
  • 创建了数据转换函数 convertToGoodsData，将API数据转换为 GoodsData 接口格式
  • 实现了触底加载更多功能，支持无限滚动
  • 添加了完整的加载状态和错误处理
  • 保持了与现有 GoodsList 和 GoodsCard 组件的完全兼容性
  • 保持了现有事件处理逻辑（商品点击、添加到购物车等）
  • 首页组件TypeScript编译正常，无错误
  • 与现有TabBarLayout完全兼容

故事6：首页轮播图改为后台广告图 ✅ (已完成)

• 完成日期: 2025-11-21
• 实施者: James (Full Stack Developer)
• 关键成果:
  • 在 mini/src/api.ts 中成功集成了 advertisementClient
  • 在 mini/src/pages/index/index.tsx 中使用 useQuery 获取广告数据
  • 实现了广告状态和类型过滤（status=1, typeId=1）
  • 保持轮播图固定高度300rpx，使用aspectFill图片填充模式
  • 添加了完整的加载状态、错误处理和空状态显示
  • 数据转换：从广告数据中提取图片URL（imageFile.fullUrl）
  • 过滤掉没有图片的广告
  • 按sort字段排序广告数据
  • 保持与现有Carousel轮播图组件的完全兼容性
  • 首页组件TypeScript编译正常，无错误
  • 与现有TabBarLayout完全兼容

故事7：用户中心UI重构 ✅ (已完成)

• 完成日期: 2025-11-21
• 实施者: James (Full Stack Developer)
• 关键成果:
  • 重构了 mini/src/pages/profile/index.tsx 用户中心页面
  • 实现了完整的TDesign组件库：user-center-card, order-group, cell-group, cell, popup
  • 应用了tcb-shop-demo用户中心设计规范，包括背景图片和布局
  • 集成了订单状态卡片（待付款、待发货、待收货、待评价）
  • 实现了功能菜单（收货地址、联系客服等）
  • 集成了客服弹窗功能，支持电话客服和在线客服
  • 完善了图标系统，添加了所有必需的图标映射
  • 保持了现有用户认证、头像上传、退出登录功能
  • 应用了1px边框处理方案和圆角设计
  • 用户中心组件TypeScript编译正常，无错误
  • 与现有TabBarLayout完全兼容

故事8：商品分类页基础组件开发 ✅ (已完成)

• 完成日期: 2025-11-21
• 实施者: James (Full Stack Developer)
• 关键成果:
  • 创建了 mini/src/components/category/CategorySidebar/index.tsx 侧边栏组件
  • 创建了 mini/src/components/category/CategorySidebarItem/index.tsx 侧边栏项组件
  • 创建了 mini/src/components/category/CategoryTabbar/index.tsx 标签栏组件
  • 创建了 mini/src/components/category/CategoryTabbarMore/index.tsx 标签栏更多组件
  • 实现了完整的子组件管理和选中状态管理
  • 实现了圆角效果管理（getTopRightRadiusItemIndexs, getBottomRightRadiusItemIndexs）
  • 应用了tcb-shop-demo设计规范：固定宽度176rpx，左侧红色指示条，文字红色圆角背景
  • 支持垂直滚动，隐藏滚动条
  • 支持水平滚动，超过4项时显示更多按钮
  • 支持下拉面板，3列网格布局
  • 支持禁用状态和悬停效果
  • 使用React Context API管理父子组件通信
  • 完整的TypeScript类型定义
  • 组件类型检查通过，无错误
  • 创建了导出文件 mini/src/components/category/index.ts
  • 提供了完整的使用文档和示例

故事10：商品列表页UI重构 ✅ (已完成)

• 完成日期: 2025-11-21
• 实施者: James (Full Stack Developer)
• 关键成果:
  • 重构了 mini/src/pages/goods-list/index.tsx 商品列表页面
  • 移除TabBarLayout包装，改为二级页面结构
  • 应用白色背景色 #fff 和灰色容器背景 #f2f2f2
  • 使用TDesign Search组件，圆角32rpx，高度64rpx
  • 商品列表改用GoodsList组件，与首页保持一致
  • 保持搜索、分类筛选、分页加载、购物车等所有功能
  • 导航栏已配置返回按钮和页面标题
  • 应用tcb-shop-demo商品列表页设计规范
  • 页面组件TypeScript编译正常，无错误