kitchen/docs/superpowers/specs/2026-04-08-refactor-design.md

全面重构设计方案

概述

本设计文档描述了对 Cute Kitchen 项目进行全面重构的方案，包括：

1. GetX 全局状态管理
2. 组件使用 PageStandards
3. 路由守卫系统
4. 组件复用方案

---

一、GetX 全局状态管理

1.1 架构设计

lib/src/controllers/
├── base/
│   ├── base_controller.dart        # 基础控制器
│   └── paged_controller.dart       # 分页控制器
├── home_controller.dart            # 首页控制器
├── cart_controller.dart            # 购物车控制器
├── profile_controller.dart         # 个人中心控制器
└── app_controller.dart             # 应用全局控制器

1.2 基础控制器

BaseController:

• 提供 isLoading 状态
• 提供 errorMessage 状态
• 提供 runWithLoading() 方法封装异步操作

PagedController:

• 继承 BaseController
• 提供 items 列表
• 提供 currentPage 当前页码
• 提供 hasMore 是否有更多数据
• 提供 loadMore() 加载更多
• 提供 refresh() 刷新数据

1.3 页面控制器

HomeController:

• 管理产品列表
• 管理分类列表
• 管理搜索和筛选状态

CartController:

• 管理购物车商品
• 计算总价
• 添加/删除商品

ProfileController:

• 管理用户信息
• 处理登录/登出

1.4 页面使用方式

• 使用 Get.put() 注册控制器
• 使用 Obx() 或 GetBuilder 监听状态变化
• 使用 Get.find() 获取控制器实例

---

二、组件使用 PageStandards

2.1 组件库结构

lib/src/widgets/
├── base/
│   ├── standard_button.dart        # 标准按钮
│   ├── standard_text_field.dart    # 标准输入框
│   ├── standard_card.dart          # 标准卡片
│   └── standard_list_tile.dart     # 标准列表项
├── interactive/
│   ├── standard_dialog.dart        # 标准对话框
│   ├── standard_bottom_sheet.dart  # 标准底部弹窗
│   └── standard_picker.dart        # 标准选择器
├── states/
│   ├── loading_indicator.dart      # 加载指示器
│   ├── empty_state.dart            # 空状态
│   ├── error_state.dart            # 错误状态
│   └── skeleton_loader.dart        # 骨架屏
└── product_card.dart               # 产品卡片（重构）

2.2 设计原则

1. 所有组件必须使用 PageStandards

   • 颜色使用 standards.primaryColor 等
   • 字体使用 standards.textStyle 等
   • 尺寸使用 standards.scaledWidth() 等

2. 支持多语言

   • 通过 standards.l10n 获取翻译

3. 支持深色模式

   • 自动跟随主题变化

2.3 标准按钮组件

StandardButton:

• 支持 4 种类型：primary、secondary、outline、text
• 支持加载状态
• 支持图标
• 支持全宽

---

三、路由守卫系统

3.1 认证级别

enum AuthLevel { 
  none,      // 无需认证
  optional,  // 可选认证
  required   // 必须认证
}

3.2 RouteGuard 类

功能:

• canAccess() - 检查是否可以访问
• getRedirectRoute() - 获取重定向路由

使用方式:

• 在 PageInfo 的 metadata 中设置 authLevel
• 在 GetPage 中调用 RouteGuard 进行验证

3.3 集成方式

GetPage(
  name: '/profile',
  page: () {
    final redirect = RouteGuard.getRedirectRoute('/profile', user: currentUser);
    if (redirect != null) {
      return LoginPage();
    }
    return const ProfilePage();
  },
),

---

四、组件复用方案

4.1 状态组件

LoadingIndicator:

• 显示加载动画
• 支持自定义大小和颜色

EmptyState:

• 显示空状态提示
• 支持自定义图标、标题、消息
• 支持操作按钮

ErrorState:

• 显示错误信息
• 支持重试按钮

4.2 交互组件

StandardDialog:

• 标准对话框
• 支持确认/取消按钮
• 提供静态 show() 方法

StandardBottomSheet:

• 标准底部弹窗
• 支持自定义内容

StandardPicker:

• 标准选择器
• 支持单选/多选

4.3 基础组件

StandardButton:

• 标准按钮
• 支持 4 种样式

StandardTextField:

• 标准输入框
• 支持验证

StandardCard:

• 标准卡片
• 支持点击事件

StandardListTile:

• 标准列表项
• 支持图标、标题、副标题

---

五、实施计划

5.1 第一阶段：基础架构

1. 创建 controllers/base/ 目录
2. 实现 BaseController
3. 实现 PagedController

5.2 第二阶段：控制器迁移

1. 创建 HomeController
2. 创建 CartController
3. 创建 ProfileController
4. 重构现有页面使用控制器

5.3 第三阶段：组件重构

1. 创建 widgets/base/ 目录
2. 实现 StandardButton
3. 实现 StandardTextField
4. 实现 StandardCard
5. 实现 StandardListTile
6. 重构 ProductCard

5.4 第四阶段：状态组件

1. 重构 LoadingIndicator
2. 实现 EmptyState
3. 实现 ErrorState
4. 重构 SkeletonLoader

5.5 第五阶段：交互组件

1. 实现 StandardDialog
2. 实现 StandardBottomSheet
3. 实现 StandardPicker

5.6 第六阶段：路由守卫

1. 实现 RouteGuard
2. 更新 PageInfo
3. 更新 main.dart

---

六、文件清单

新增文件

文件路径	说明
lib/src/controllers/base/base_controller.dart	基础控制器
lib/src/controllers/base/paged_controller.dart	分页控制器
lib/src/controllers/home_controller.dart	首页控制器
lib/src/controllers/cart_controller.dart	购物车控制器
lib/src/controllers/profile_controller.dart	个人中心控制器
lib/src/controllers/app_controller.dart	应用全局控制器
lib/src/widgets/base/standard_button.dart	标准按钮
lib/src/widgets/base/standard_text_field.dart	标准输入框
lib/src/widgets/base/standard_card.dart	标准卡片
lib/src/widgets/base/standard_list_tile.dart	标准列表项
lib/src/widgets/interactive/standard_dialog.dart	标准对话框
lib/src/widgets/interactive/standard_bottom_sheet.dart	标准底部弹窗
lib/src/widgets/interactive/standard_picker.dart	标准选择器
lib/src/widgets/states/empty_state.dart	空状态
lib/src/widgets/states/error_state.dart	错误状态
lib/src/standards/route_guard.dart	路由守卫

修改文件

文件路径	修改内容
lib/src/pages/home_page.dart	使用 HomeController
lib/src/pages/example_page.dart	使用 PageStandards
lib/src/pages/theme_demo_page.dart	使用控制器
lib/src/widgets/product_card.dart	使用 PageStandards
lib/src/widgets/loading_indicator.dart	使用 PageStandards
lib/src/widgets/skeleton_loader.dart	使用 PageStandards
lib/src/standards/app_pages.dart	添加 authLevel
lib/main.dart	集成路由守卫
CHANGELOG.md	更新日志

---

七、验收标准

1. ✅ 所有页面使用 GetX 状态管理
2. ✅ 所有组件使用 PageStandards
3. ✅ 路由守卫正常工作
4. ✅ 组件可复用
5. ✅ 代码分析无错误
6. ✅ 深色模式正常切换
7. ✅ 多语言正常工作

---

创建时间： 2026-04-08 作者： AI Assistant