# flutter-demo

**Repository Path**: abcbox1/flutter-demo

## Basic Information

- **Project Name**: flutter-demo
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-08
- **Last Updated**: 2026-07-08

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Flutter Shop — 教学型全功能商城项目

> **从零到一构建的 Flutter 商城应用**，以架构师视角融入主流 Flutter 技术栈，代码附详细注释以便系统学习。

## 项目概览

| 维度 | 说明 |
|------|------|
| 框架 | Flutter 3.x + Dart 3.x |
| 架构 | Clean Architecture（分层）+ MVVM（表现层）+ 设计模式驱动 |
| 状态管理 | Riverpod 2.x（UI 状态）+ GetIt（服务层 DI） |
| 路由 | GoRouter（声明式路由 + 权限守卫） |
| 网络 | Dio 5.x（拦截器链 + 请求取消） |
| 存储 | SharedPreferences + Hive + SecureStorage（三级存储） |
| 文件数 | 167 个 Dart 源文件 |

## 项目结构

```
lib/
├── main.dart                          # 应用入口（Zone 隔离 + 三层错误捕获）
├── app/                               # 应用配置
│   ├── themes/                        # 主题（Material 3 + 亮色/暗色）
│   ├── routes/                        # 路由（GoRouter + 权限守卫）
│   └── l10n/                          # 国际化（中文/英文）
├── core/                              # 核心基础设施（与业务无关）
│   ├── network/                       # 网络层（Dio 单例 + 4 层拦截器链）
│   │   └── interceptors/              # 认证/日志/重试/错误拦截器
│   ├── storage/                       # 存储层（LRU 缓存 + 三级缓存代理）
│   ├── error/                         # 错误处理（三层捕获 + 优先队列上报）
│   ├── tracing/                       # 全链路跟踪（Zone 隔离 + Trace ID）
│   ├── heartbeat/                     # 心跳检测（指数退避重连）
│   ├── permission/                    # 权限控制（RBAC + 生物认证）
│   ├── di/                            # 依赖注入（GetIt 服务定位器）
│   └── constants/                     # 全局常量
├── data/                              # 数据层
│   ├── models/                        # 数据模型 DTO（fromJson/toJson + Mock）
│   ├── datasources/                   # 数据源（远程 Mock + 本地持久化）
│   ├── repositories/                  # 仓库实现（代理/观察者模式）
│   └── mappers/                       # 映射器（DTO ↔ Entity）
├── domain/                            # 领域层（纯业务逻辑，不依赖框架）
│   ├── entities/                      # 领域实体 + 枚举
│   ├── repositories/                  # 仓库接口（依赖倒置）
│   └── usecases/                      # 用例（命令模式 + 撤销栈）
├── presentation/                      # 表现层
│   ├── pages/                         # 18 个页面（首页/分类/搜索/详情/购物车/订单/物流/售后/客服/个人中心等）
│   ├── providers/                     # 14 个 Riverpod Provider
│   └── widgets/                       # 15 个共享组件
├── services/                          # 服务层
│   ├── payment/                       # 支付服务（策略模式 + 生物认证）
│   ├── websocket/                     # WebSocket 服务（消息队列 + 心跳联动）
│   └── analytics/                     # 埋点分析（与 Tracing 联动）
└── utils/                             # 工具层
    ├── extensions/                    # Dart 扩展方法
    ├── validators/                    # 表单验证器
    └── helpers/                       # 辅助函数
```

## 设计模式映射（10 种）

| 设计模式 | 运用位置 | 文件 |
|---------|---------|------|
| **单例模式** | 网络客户端、存储管理器 | `core/network/api_client.dart` |
| **工厂模式** | 数据模型反序列化 | `data/models/*.dart` (fromJson) |
| **观察者模式** | 购物车变化通知、网络状态通知 | `data/repositories/cart_repository_impl.dart` |
| **策略模式** | 支付方式切换、重连退避算法 | `services/payment/payment_strategy.dart` |
| **装饰器模式** | 网络请求拦截器链 | `core/network/interceptors/` |
| **适配器模式** | 支付 SDK 适配、生物认证适配 | `services/payment/payment_strategy.dart` |
| **代理模式** | 商品缓存代理 | `data/repositories/product_repository_impl.dart` |
| **命令模式** | 购物车操作（可撤销） | `domain/usecases/cart/cart_usecase.dart` |
| **责任链模式** | 权限校验链、错误处理链 | `core/permission/permission_guard.dart` |
| **模板方法** | 页面加载/错误/空状态处理 | `presentation/widgets/` |

## 数据结构映射（7 种）

| 数据结构 | 运用位置 | 文件 |
|---------|---------|------|
| **队列** | 消息发送队列、日志上报队列 | `services/websocket/websocket_service.dart` |
| **栈** | 购物车操作撤销栈 | `domain/usecases/cart/cart_usecase.dart` |
| **树** | 商品分类树、省市区地址树 | `data/models/category_model.dart` |
| **哈希表** | 购物车映射、LRU 缓存 | `core/storage/lru_cache.dart` |
| **链表** | LRU 缓存（LinkedHashMap） | `core/storage/lru_cache.dart` |
| **集合** | 搜索历史去重、受保护路由集合 | `presentation/providers/search_provider.dart` |
| **优先队列** | 错误日志优先级调度 | `core/error/error_log_queue.dart` |

## 功能模块

### P0 核心功能
- ✅ 用户认证（手机号验证码登录 + Token 管理 + 自动登录）
- ✅ 商品首页（Banner 轮播 + 分类导航 + 推荐商品流 + 下拉刷新）
- ✅ 商品分类（树形结构 + 双栏布局）
- ✅ 商品搜索（搜索历史 + 热门搜索 + 筛选排序）
- ✅ 商品详情（图片轮播 + SKU 选择 + 评价 + 加入购物车）
- ✅ 购物车（增删改 + 选中/全选 + 价格计算 + 命令模式撤销）
- ✅ 订单管理（下单流程 + 多状态 Tab + 订单详情）
- ✅ 支付系统（策略模式 + 微信/支付宝/Mock + 生物认证 + 状态轮询）
- ✅ 物流跟踪（轨迹时间线 + 状态机 + 轮询更新）
- ✅ 售后系统（退款/退货/换货 + 状态机 + 凭证上传）
- ✅ LLM 智能客服（WebSocket 流式对话 + 上下文感知 + 断线重连）
- ✅ 收货地址（省市区联动 + 默认设置）
- ✅ 个人中心（用户信息 + 订单快捷入口 + 功能列表）

### P1 工程化能力
- ✅ 全链路跟踪（Zone 隔离 + Trace ID 贯穿 + 批量上报）
- ✅ 错误日志上报（三层捕获 + 优先队列 + 本地持久化重传）
- ✅ 心跳检测（Timer 驱动 + 指数退避重连 + 观察者通知）
- ✅ 权限控制（RBAC + 路由守卫 + 生物认证）
- ✅ 网络层架构（Dio 封装 + 4 层拦截器 + Token 自动刷新）
- ✅ 多级缓存（内存 LRU → 磁盘 Hive → 网络）
- ✅ 多设备适配（LayoutBuilder 断点 + SafeArea + NavigationRail）
- ✅ 动画交互（Hero 转场 + Shimmer 骨架屏 + 流式打字动画）
- ✅ 状态管理（Riverpod 全局/局部状态分离）
- ✅ 国际化与主题（中英文 + 亮色/暗色切换）

## 启动方式

```bash
# 1. 安装依赖
flutter pub get

# 2. 运行项目（Mock 模式，无需后端）
flutter run

# 3. 构建发布包
flutter build apk --release    # Android
flutter build ios --release     # iOS
```

## Mock 模式

项目内置 Mock 数据开关（`ApiConstants.useMock = true`），所有 Remote DataSource 在 Mock 模式下返回内置真实数据，无需后端即可完整运行。

关闭 Mock：修改 `lib/core/constants/api_constants.dart` 中 `useMock = false`。

## 技术文档

- [PRD 产品需求文档](docs/PRD.md) — 产品经理 许清楚
- [系统架构设计](docs/ARCHITECTURE.md) — 架构师 高见远
- [类图](docs/class-diagram.mermaid) — 核心模型关系
- [时序图](docs/sequence-diagram.mermaid) — 5 个关键流程

## 团队

| 角色 | 姓名 | 职责 |
|------|------|------|
| 交付总监 | 齐活林（Qi） | 团队协调与流程编排 |
| 产品经理 | 许清楚（Xu） | PRD 文档与需求分析 |
| 架构师 | 高见远（Gao） | 系统设计与任务分解 |
| 工程师 | 寇豆码（Kou） | 代码实现与一致性审查 |
| QA 工程师 | 严过关（Yan） | 测试验证与回归 |

---

> 本项目以 **代码 = SOP(团队)** 理念构建，每一步产出均由对应专业角色负责。