App.K12.Student.Miniapp_Flutter/docs/flutter_learning_journey.md

# Flutter 学习全旅程讲解 — 从零到生产级项目

> **预计时长：40 分钟** | **项目：`new_learn`** | **Flutter 3.44.x + Dart 3.12**

---

## 目录

| 章节 | 主题 | 预估时长 |
|------|------|----------|
| 一 | 环境安装与项目初始化 | ~4 min |
| 二 | Dart 3 语法核心要点 | ~4 min |
| 三 | Flutter 3 核心框架与分层架构 | ~5 min |
| 四 | 全局状态管理：Riverpod 方案 | ~4 min |
| 五 | Dio 网络请求生产级封装 | ~4 min |
| 六 | 屏幕适配：ScreenUtil 方案 | ~3 min |
| 七 | 多品牌主题配置体系 | ~3 min |
| 八 | 多环境变量配置体系 | ~3 min |
| 九 | 本地存储：Isar + 响应式 watch | ~3 min |
| 十 | Demo 组件封装思路汇总 | ~5 min |
| 十一 | 学习路径与心得总结 | ~2 min |

---

## 一、环境安装与项目初始化（~4 min）

### 1.1 工具链一览

| 工具 | 版本 | 用途 |
|------|------|------|
| Flutter SDK | 3.44.x | 编译、热重载、多端构建 |
| Dart SDK | 3.12 | 语言运行时 |
| Android Studio / VS Code | 最新 | IDE + 插件 |
| Android SDK | API 34+ | 安卓构建 |
| Xcode | 15+（Mac） | iOS 构建 |

> 本项目路径：`D:\dev\flutter_3.44.8\flutter`（见 [local.properties](file:///d:/flutter_learn/new_learn/android/local.properties)）

### 1.2 创建项目

```bash
flutter create --org com.example --platforms=android,ios,web,windows new_learn
```

### 1.3 项目核心依赖

完整依赖见 [pubspec.yaml](file:///d:/flutter_learn/new_learn/pubspec.yaml)，关键项：

```yaml
environment:
  sdk: ^3.12.2

dependencies:
  flutter: { sdk: flutter }
  dio: ^5.10.0                         # 网络请求
  go_router: ^17.4.0                  # 声明式路由
  flutter_riverpod: ^3.3.2            # 状态管理
  flutter_screenutil: ^5.9.0          # 屏幕适配

  cached_network_image: ^3.4.1         # 网络图片缓存（ImageDemo）
  infinite_scroll_pagination: ^5.1.1   # 分页列表
  flutter_widget_from_html_core: ^0.17.2 # 富文本 HTML 渲染

  shared_preferences: ^2.5.3           # 轻量本地存储
  flutter_secure_storage: ^9.2.4       # 敏感凭据安全存储
  isar_community: ^3.3.2               # 本地数据库
  isar_community_flutter_libs: ^3.3.2
  path_provider: ^2.1.5

  wechat_assets_picker: ^9.8.0         # 相册多选/预览（原生端）
  wechat_camera_picker: ^4.6.0         # 微信风格相机（原生端）
  image_picker: ^1.2.3                 # Web 兜底图片选择
  permission_handler: ^11.3.1          # 权限管理

  image: ^4.8.0                        # 纯 Dart 图片处理（含 Web）
  flutter_image_compress: ^2.5.1       # 原生压缩（Android/iOS）
  photo_view: ^0.15.0                  # 图片预览缩放

  video_player: ^2.13.0                # 视频播放
  chewie: ^1.13.1                      # 视频 UI 封装
  just_audio: ^0.10.6                  # 音频播放

  share_plus: ^10.1.4                  # 系统分享
  gal: ^2.3.3                          # 保存到相册
  package_info_plus: ^8.3.0            # 版本信息
  url_launcher: ^6.3.1                 # 外部跳转
  smooth_sheets: ^1.1.1                # 常驻底部面板

  crypto: ^3.0.6                       # MD5 等加密
  # 完整依赖与注释说明以 pubspec.yaml 为准（此处为学习旅程的“关键依赖速览”）
```

### 1.4 目录结构

```
lib/
├── main.dart                    # 启动入口（5步初始化）
├── core/                        # 核心基础设施层
│   ├── app.dart                 # 根组件 TabApp
│   ├── config/                  # 环境+品牌配置
│   ├── network/                 # Dio 封装 + API
│   ├── providers/               # Riverpod 全局状态
│   ├── router/                  # go_router 路由表
│   ├── theme/                   # 多品牌主题
│   ├── storage/                 # Isar + 安全存储
│   ├── services/                # 图片/选择/分享服务
│   └── components/              # 9个可复用组件
├── features/                    # 业务功能层
│   ├── auth/                    # 登录+隐私协议
│   ├── exam/                    # 试卷练习
│   ├── my/                      # 个人中心
│   └── ...
└── pages/demo/                  # 28个独立学习Demo
```

> **讲解要点**：这套 `core / features / pages` 三层分离，对标前端 `utils / views / components`，让基础设施和业务逻辑彻底解耦。

---

## 二、Dart 3 语法核心要点（~4 min）

### 2.1 与 JavaScript/TypeScript 的关键差异

| 概念 | JS/TS | Dart 3 |
|------|-------|--------|
| 类型声明 | `let x: number` | `int x` / `var x`（类型推断）|
| 空安全 | 可选 `?` | 健全空安全 `String?`，编译期拦截 |
| 异步 | Promise | `Future` + `async/await` |
| 集合 | Array/Map | `List<T>` / `Map<K,V>` / `Set<T>` |
| 类 | class | class + `mixin` 混入 |
| 模式匹配 | 无 | `switch` 表达式 + 解构（Dart 3 新特性）|

### 2.2 空安全（Sound Null Safety）

```dart
String name = 'Flutter';    // 不可为 null
String? nickname;           // 可为 null，使用前必须判空

// 安全调用
int len = nickname?.length ?? 0;   // ?. + ?? 兜底
```

> **核心规则**：所有变量默认非空，`?` 才允许 null。编译期就帮你拦住空指针。

### 2.3 异步编程
`fromJson` 是构造函数，把字典转换成我们定义的 User 实体类对象，获得类型安全、点访问、编译检查。

```dart
Future<User> fetchUser() async {
  final response = await dio.get('/user');
  return User.fromJson(response.data);
}
```

### 2.4 模式匹配（Dart 3 特性）

```dart
// switch 表达式
String describe(Object obj) => switch (obj) {
  int() => '整数',
  String() => '字符串',
  List<int>() => '整数列表',
  _ => '未知',
};
```

### 2.5 类与混入

```dart
mixin Disposable {
  void dispose();
}

class MyController with Disposable {
  @override
  void dispose() { /* 释放资源 */ }
}
```

> **讲解要点**：Dart 3 的空安全是「健全」的，编译期保证非空变量不会拿到 null，比 TS 的可选链更彻底。模式匹配让分支逻辑更简洁。

---

## 三、Flutter 3 核心框架与分层架构（~5 min）

### 3.1 Widget 是什么？

**核心认知**：Widget 是「配置对象」不是「渲染 View」。

```
Widget（配置蓝图）→ Element（实例化树节点）→ RenderObject（真正测量布局绘制）
```

- `StatelessWidget`：纯展示，props 不变 → 如 `Text`、`Icon`
- `StatefulWidget`：有内部状态，`setState` 触发重建 → 如 `Checkbox`、`TextField`

### 3.2 核心布局原理

> **Flutter 布局第一法则**：父组件向子组件传递**约束（Constraints）**，子组件根据约束**决定自身大小（Size）**，然后向上返回。

```
父 Widget  ──Constraints──>  子 Widget
                              ↓ 决定自身大小
父 Widget  <──Size──────────  子 Widget
```

- **主轴**（MainAxis）：Row 的水平方向 / Column 的垂直方向
- **交叉轴**（CrossAxis）：与主轴垂直的方向

### 3.3 启动流程链路

入口文件 [main.dart](file:///d:/flutter_learn/new_learn/lib/main.dart)：

```
main()  5步串行初始化
  ↓
1. WidgetsFlutterBinding.ensureInitialized()   // 插件通道就绪
2. GoRouter.optionURLReflectsImperativeAPIs   // 修复 web 地址栏同步
3. DioClient.instance.restoreToken()           // 回填登录 Token
4. privacyAcceptedNotifier                     // 恢复隐私协议状态
5. AppDatabase.instance.init()                 // 初始化 Isar
  ↓
runApp(ProviderScope(child: TabApp()))         // Riverpod 容器 + 根组件
```

根组件 [app.dart](file:///d:/flutter_learn/new_learn/lib/core/app.dart)：

```
TabApp (StatelessWidget)
  └─ ScreenUtilInit          // 屏幕适配
      └─ MaterialApp.router  // Material3 + 品牌种子色
          ├─ builder: PrivacyStartupGate    // 启动层隐私拦截
          └─ routerConfig: appRouter         // 全局路由表
```

### 3.4 路由体系

路由表 [app_router.dart](file:///d:/flutter_learn/new_learn/lib/core/router/app_router.dart)：

```
GoRouter
  ├─ redirect: _guardLogin              // 登录守卫（对标 vue-router beforeEach）
  │   ├─ 未同意隐私 → /privacy-consent
  │   ├─ 已同意+在隐私页 → /login 或 /
  │   ├─ 未登录 → /login
  │   └─ 已登录+在登录页 → /
  ├─ refreshListenable: authTick + privacyNotifier  // 响应式守卫
  ├─ ShellRoute (4 tab 壳)
  │   ├─ /         → TaskPage
  │   ├─ /recite   → RecitePage
  │   ├─ /class    → ClassPage
  │   └─ /my       → MyPage
  ├─ /privacy-consent
  ├─ /login
  └─ /myPoint
```

> **讲解要点**：go_router 的 `refreshListenable` 是核心 — 登录态变化时自动 `refresh()` 重算 redirect，不需要手动跳转，对标 Vue Router 的响应式 `beforeEach`。

---

## 四、全局状态管理：Riverpod 方案（~4 min）

### 4.1 为什么选 Riverpod？

| 维度 | Provider（旧） | Riverpod 3.x |
|------|----------------|--------------|
| 依赖注入 | `context.read()` 耦合 BuildContext | 全局容器，不依赖 context |
| 测试 | 难 mock | `ProviderContainer` 轻量覆盖 |
| 安全 | 运行时报错 | 编译期检查（Provider 不可缺）|
| 异步 | 手写 FutureBuilder | AsyncNotifier 内建 loading/error/data |

### 4.2 本项目的两种状态方案

#### 方案 A：ValueNotifier — 轻量全局信号

隐私协议状态 [privacy_provider.dart](file:///d:/flutter_learn/new_learn/lib/core/providers/privacy_provider.dart)：

```dart
final ValueNotifier<bool> privacyAcceptedNotifier = ValueNotifier<bool>(false);
```

> **为什么不用 Riverpod？** go_router 的 `refreshListenable` 需要 `Listenable`，ValueNotifier 足够轻量，且 `main()` 中 `runApp` 前就能直接恢复状态。

#### 方案 B：Riverpod AsyncNotifier — 全局用户状态

用户状态 [user_provider.dart](file:///d:/flutter_learn/new_learn/lib/core/providers/user_provider.dart)：

```dart
class CurrentUserNotifier extends AsyncNotifier<CurrentUserExtension?> {
  @override
  Future<CurrentUserExtension?> build() async {
    // 冷启动异步从本地缓存回填
    return await UserStorage.instance.readUser();
  }

  void set(user) {
    state = AsyncData(user);           // 有值
    authTick.value++;                  // 触发路由守卫重算
  }
}

// 全局 Provider
final currentUserProvider =
    AsyncNotifierProvider<CurrentUserNotifier, CurrentUserExtension?>(...);
```

状态四态生命周期：

```
AsyncLoading()    → 正在读缓存
AsyncData(user)   → 有值（已登录）
AsyncData(null)   → 明确未登录
AsyncError(e)     → 异常
```

> **讲解要点**：`authTick`（ValueNotifier<int>）是登录态变化的信号源，Riverpod 写状态、ValueNotifier 通知路由，两者协作实现「响应式登录守卫」。

---

## 五、Dio 网络请求生产级封装（~4 min）

### 5.1 封装架构

核心文件 [dio_client.dart](file:///d:/flutter_learn/new_learn/lib/core/network/dio_client.dart)：

```
DioClient (单例)
  ├─ BaseOptions
  │   ├─ baseUrl  → 来自 AppConfig（品牌×环境组合）
  │   └─ 超时：连接 15s / 接收 15s / 发送 15s
  ├─ 拦截器三件套
  │   ├─ onRequest  → 自动加 Authorization: Bearer token
  │   ├─ onResponse → 日志打印
  │   └─ onError    → 401清Token + DioException→ApiException
  ├─ 泛型请求方法
  │   ├─ get<T>(path, {cancelToken, queryParameters})
  │   ├─ post<T>(path, {data, cancelToken, onSendProgress})
  │   └─ put<T>(path, {data})
  └─ restoreToken() → 冷启动回填 Token
```

### 5.2 统一异常翻译

```dart
// UI 层只需要 catch ApiException，不用管 DioException
ApiException _mapError(DioException e) {
  switch (e.type) {
    case DioExceptionType.connectionTimeout:
      return ApiException('网络连接超时，请检查网络');
    case DioExceptionType.connectionError:
      return ApiException('网络连接失败，请检查网络');
    // ... badResponse / cancel / unknown
  }
}
```

### 5.3 生产级能力（Demo 演示）

| 能力 | 实现方式 | Demo |
|------|----------|------|
| 下载进度 | `onReceiveProgress` 回调 | [dio_pro_demo.dart](file:///d:/flutter_learn/new_learn/lib/pages/demo/dio_pro_demo.dart) |
| 取消请求 | `CancelToken` + dispose 自动取消 | 同上 |
| 失败重试 | 指数退避 `_canRetry`（仅网络层错误）| 同上 |
| Token 自动注入 | 拦截器 onRequest | dio_client.dart |
| 401 自动登出 | 拦截器 onError | dio_client.dart |
| OSS 直传 | 已有 authorization 头时跳过注入 | [oss_uploader.dart](file:///d:/flutter_learn/new_learn/lib/core/network/oss_uploader.dart) |

### 5.4 数据模型 fromJson

```dart
// user_model.dart — 防御性解析，兼容后端返回字符串数字
factory CurrentUserExtension.fromJson(Map<String, dynamic> json) {
  return CurrentUserExtension(
    userId: json['userId'] as int,
    userNo: json['userNo']?.toString() ?? '',
    level: _toInt(json['level']),       // 兼容 "1" 或 1
    balance: _toDouble(json['balance']),
    // ... 17 个字段
  );
}
```

> **讲解要点**：`fromJson` 用 `_toInt` / `_toDouble` 兜底，是真实项目中最常见的后端类型不稳定问题。UI 层永远只 catch `ApiException` 一个类型。

---

## 六、屏幕适配：ScreenUtil 方案（~3 min）

### 6.1 核心文件

适配模板 [screen_adapt_template.dart](file:///d:/flutter_learn/new_learn/lib/core/utils/screen_adapt_template.dart)：

```
AppAdapt 工具类
  ├─ tabletBreakpoint = 600          // Material 平板断点
  ├─ phoneDesign = Size(375, 812)    // iPhone 逻辑尺寸
  ├─ designSizeOf(context)           // 方案B：平板用设备自身尺寸
  └─ fontSizeResolver                // 方案A：字体放大封顶 1.2 倍
```

### 6.2 双方案策略

| 方案 | 目标 | 实现 |
|------|------|------|
| 方案 A | 大屏字体不过分放大 | `fontSizeResolver` 封顶 `maxFontScale=1.2` |
| 方案 B | 平板布局不被拉伸 | 宽高都 ≥600dp 时用设备自身尺寸做 designSize，缩放回到 ~1 |

### 6.3 使用规则

```dart
// 字号：用 .spMin（大屏只缩不放）
Text('你好', style: TextStyle(fontSize: 16.spMin));

// 宽度/横向间距：用 .w
SizedBox(width: 16.w);

// 高度/纵向：用 .h
SizedBox(height: 48.h);

// 圆角：用 .r
BorderRadius.circular(8.r);
```

> **讲解要点**：字号必须用 `.spMin` 而非 `.sp` — `.sp` 在大屏会把字体放得过大，`.spMin` 确保只缩小不放大。

---

## 七、多品牌主题配置体系（~3 min）

### 7.1 三层解耦设计

```
环境（接口在哪）  →  app_env.dart     编译期 --dart-define 定死
品牌（谁家 App）  →  app_brand.dart   发布期定死，7个品牌
主题（长什么样）  →  brand_theme.dart  运行时可切换
配置聚合           →  app_config.dart  全项目唯一取配置入口
```

### 7.2 两级主题模型

模型文件 [brand_theme.dart](file:///d:/flutter_learn/new_learn/lib/core/theme/brand_theme.dart)：

```
BrandTheme（一级品牌）
  ├─ name: 'SkyBlue'
  ├─ seedColor: Color(0xFF4FC3F7)     // 种子色 → Material3 自动生成整套色板
  └─ pages: Map<PageLevel, PageTheme>
      ├─ home:    PageTheme { bg, headerBg, accent, title, banner }
      ├─ detail:  PageTheme { ... }
      └─ result:  PageTheme { ... }
```

品牌主题文件：
- [sky_blue_theme.dart](file:///d:/flutter_learn/new_learn/lib/core/theme/brands/sky_blue_theme.dart) — seedColor `0xFF4FC3F7`
- [red_theme.dart](file:///d:/flutter_learn/new_learn/lib/core/theme/brands/red_theme.dart) — seedColor `0xFFEF4444`

### 7.3 新增主题三步走

```
1. 在 brands/ 下新建 xxx_theme.dart → 定义 seedColor + 三层级配置
2. 在 brand_theme.dart 中 import + 添加到 brandThemes 列表
3. 在 app_brand.dart 中给品牌指定 themeId
```

> **讲解要点**：「模型文件不写颜色、品牌文件不写逻辑」— 新增主题零改页面代码。`colorSchemeSeed` 让 Material 3 自动从种子色生成完整配色。

---

## 八、多环境变量配置体系（~3 min）

### 8.1 编译期注入

环境配置 [app_env.dart](file:///d:/flutter_learn/new_learn/lib/core/config/app_env.dart)：

```dart
// 编译期注入，默认 prod
static const String env = String.fromEnvironment('ENV', defaultValue: 'prod');
static const String brand = String.fromEnvironment('BRAND', defaultValue: 'aixue');
```

### 8.2 三套环境地址

| 环境 | baseUrl | 用途 |
|------|---------|------|
| dev | `k12-student-api-test.23544.com:16400` | 本地开发联调 |
| test | `axdb-test.cnzhyx.cn` | 测试环境 |
| prod | `ylax-api.cqbzyx.com`（被品牌专属地址覆盖）| 生产 |

### 8.3 运行命令

```bash
# 开发环境 + 爱学蝶变品牌
flutter run --dart-define=ENV=dev --dart-define=BRAND=aixue

# 生产环境 + 楚才品牌
flutter run --dart-define=ENV=prod --dart-define=BRAND=chucai

# 构建 APK
flutter build apk --dart-define=ENV=prod --dart-define=BRAND=chucai
```

### 8.4 配置聚合层

[app_config.dart](file:///d:/flutter_learn/new_learn/lib/core/config/app_config.dart) — 全项目唯一取配置入口：

```dart
// baseUrl 规则：prod 用品牌专属地址覆盖，否则环境通用地址
static String get baseUrl =>
    AppEnv.isProd ? (currentBrand.baseUrl ?? AppEnv.baseUrl) : AppEnv.baseUrl;

// 主题：按品牌查主题注册表，未知兜底第一个
static BrandTheme get theme =>
    brandThemes.firstWhere((t) => t.name == currentBrand.themeId,
        orElse: () => brandThemes.first);
```

> **讲解要点**：`String.fromEnvironment` 是编译期常量，不占运行时开销。品牌 × 环境组合让一套代码出 7 个品牌的 App，只需改运行命令。

---

## 九、本地存储：Isar + 响应式 watch（~3 min）

### 9.1 存储组合

| 存储方式 | 用途 | 文件 |
|----------|------|------|
| `flutter_secure_storage` | Token 安全存储 | [user_storage.dart](file:///d:/flutter_learn/new_learn/lib/core/storage/user_storage.dart) |
| `shared_preferences` | 隐私协议同意状态 | [privacy_storage.dart](file:///d:/flutter_learn/new_learn/lib/core/storage/privacy_storage.dart) |
| `isar_community` | 题库/错题/播放记录 | [app_database.dart](file:///d:/flutter_learn/new_learn/lib/core/storage/database/app_database.dart) |

### 9.2 Isar 数据模型

```dart
@collection
class WrongQuestion {
  Id id = Isar.autoIncrement;
  late int questionId;
  late int userId;
  late String questionTitle;
  late DateTime createdAt;
}
```

> 通过 `build_runner` 生成 `.g.dart`，提供类型安全的 CRUD。

### 9.3 平台分流实现

```
app_database.dart          → 抽象接口
  ├─ app_database_io.dart   → 原生平台 Isar 实现
  └─ app_database_web.dart  → Web 调试自动跳过（Isar 不支持 Web）
```

### 9.4 watch 响应式 — 错题自动刷新

Demo 演示 [isar_watch_demo.dart](file:///d:/flutter_learn/new_learn/lib/pages/demo/isar_watch_demo.dart)：

```dart
// Isar watch：数据变化自动通知 UI 刷新
Stream<List<WrongQuestion>> watchWrongQuestions() {
  return database.wrongQuestions
      .where()
      .userIdEqualTo(userId)
      .watch(fireImmediately: true);
}
```

> **讲解要点**：Isar 的 `watch()` 是真正的响应式 — 数据库写入后自动通知 Stream 监听者，UI 无需手动刷新。对标前端的「数据驱动视图」，但是是本地数据库级别的。

---

## 十、Demo 组件封装思路汇总（~5 min）

### 10.1 28 个 Demo 的分类学习路径

#### 第一阶段：基础组件

| Demo | 核心知识点 | 代码 |
|------|-----------|------|
| Text | 样式/截断/富文本/手势 | [text_demo.dart](file:///d:/flutter_learn/new_learn/lib/pages/demo/text_demo.dart) |
| Image | 四种来源 + BoxFit + 错误兜底 | [image_demo.dart](file:///d:/flutter_learn/new_learn/lib/pages/demo/image_demo.dart) |
| Input | controller + dispose + 密码显隐 | [input_demo.dart](file:///d:/flutter_learn/new_learn/lib/pages/demo/input_demo.dart) |
| Align | 对齐 + Riverpod 全局信息 | [align_demo.dart](file:///d:/flutter_learn/new_learn/lib/pages/demo/align_demo.dart) |
| Stack | 层叠 + 全 Positioned 尺寸坑 | [stack_demo.dart](file:///d:/flutter_learn/new_learn/lib/pages/demo/stack_demo.dart) |
| Wrap | 自动换行 + Chip + 自绘 CustomTag | [wrap_demo.dart](file:///d:/flutter_learn/new_learn/lib/pages/demo/wrap_demo.dart) |

#### 第二阶段：布局进阶

| Demo | 核心知识点 | 代码 |
|------|-----------|------|
| List | 懒加载/下拉刷新/触底加载 | [list_demo.dart](file:///d:/flutter_learn/new_learn/lib/pages/demo/list_demo.dart) |
| Grid | count/builder/extent 三种构造 | [grid_demo.dart](file:///d:/flutter_learn/new_learn/lib/pages/demo/grid_demo.dart) |
| Sliver | CustomScrollView + 折叠 AppBar | [sliver_demo.dart](file:///d:/flutter_learn/new_learn/lib/pages/demo/sliver_demo.dart) |
| Responsive | 手机单列 vs Pad 多列 | [responsive_demo.dart](file:///d:/flutter_learn/new_learn/lib/pages/demo/responsive_demo.dart) |

#### 第三阶段：路由与表单

| Demo | 核心知识点 | 代码 |
|------|-----------|------|
| Router | 命名路由表 + 三种跳转姿势 | [router_home_page.dart](file:///d:/flutter_learn/new_learn/lib/pages/demo/router_home_page.dart) |
| Detail | 构造传参 vs 命名路由 arguments | [detail_page.dart](file:///d:/flutter_learn/new_learn/lib/pages/demo/detail_page.dart) |
| Form | 7 个校验知识点/两段式提交 | [form_demo.dart](file:///d:/flutter_learn/new_learn/lib/pages/demo/form_demo.dart) |
| Picker | pop 带值返回 | [picker_page.dart](file:///d:/flutter_learn/new_learn/lib/pages/demo/picker_page.dart) |

#### 第四阶段：网络与数据

| Demo | 核心知识点 | 代码 |
|------|-----------|------|
| Dio | GET/POST/错误兜底三态 UI | [dio_demo.dart](file:///d:/flutter_learn/new_learn/lib/pages/demo/dio_demo.dart) |
| Dio Pro | 下载进度/CancelToken/重试 | [dio_pro_demo.dart](file:///d:/flutter_learn/new_learn/lib/pages/demo/dio_pro_demo.dart) |
| Isar Watch | 错题本自动刷新 | [isar_watch_demo.dart](file:///d:/flutter_learn/new_learn/lib/pages/demo/isar_watch_demo.dart) |
| Wrong Flow | 接口+Isar+watch 完整链路 | [wrong_flow_demo.dart](file:///d:/flutter_learn/new_learn/lib/pages/demo/wrong_flow_demo.dart) |
| OSS Upload | 客户端签名+PUT直传 | [oss_upload_demo.dart](file:///d:/flutter_learn/new_learn/lib/pages/demo/oss_upload_demo.dart) |

#### 第五阶段：主题与媒体

| Demo | 核心知识点 | 代码 |
|------|-----------|------|
| Theme | 两级主题模型 + 品牌换肤 | [theme_demo.dart](file:///d:/flutter_learn/new_learn/lib/pages/demo/theme_demo.dart) |
| Seed Palette | colorSchemeSeed 自动生成配色 | [seed_palette_demo.dart](file:///d:/flutter_learn/new_learn/lib/pages/demo/seed_palette_demo.dart) |
| Animation | 隐式/显式/Hero/CustomPaint | [animation_demo.dart](file:///d:/flutter_learn/new_learn/lib/pages/demo/animation_demo.dart) |
| Rich Text | HTML 题目渲染 + audio 替换 | [rich_text_demo.dart](file:///d:/flutter_learn/new_learn/lib/pages/demo/rich_text_demo.dart) |
| Audio | just_audio 控制条 | [audio_player_demo.dart](file:///d:/flutter_learn/new_learn/lib/pages/demo/audio_player_demo.dart) |
| Share | 文本/图片/截图海报/存相册 | [share_demo.dart](file:///d:/flutter_learn/new_learn/lib/pages/demo/share_demo.dart) |
| Smooth Sheet | 常驻多停靠底部面板 | [smooth_sheet_demo.dart](file:///d:/flutter_learn/new_learn/lib/pages/demo/smooth_sheet_demo.dart) |

### 10.2 核心组件封装思路（9个可复用组件）

| 组件 | 封装思路 | 代码 |
|------|----------|------|
| **PrivacyStartupGate** | 启动层隐私 Gate — 冷启动不闪登录页，视觉第一拦 | [privacy_startup_gate.dart](file:///d:/flutter_learn/new_learn/lib/core/components/privacy_startup_gate.dart) |
| **CommonPagedList** | 通用分页列表 — 基于 infinite_scroll_pagination，对标 z-paging | [common_paged_list.dart](file:///d:/flutter_learn/new_learn/lib/core/components/common_paged_list.dart) |
| **AudioPlayerCard** | 通用音频控制条 — 播放/进度/倍速/循环，切后台自动暂停 | [audio_player_card.dart](file:///d:/flutter_learn/new_learn/lib/core/components/audio_player_card.dart) |
| **VideoPlayerView** | 通用视频播放器内嵌版 — 无 Scaffold，可嵌入任意位置 | [video_player_view.dart](file:///d:/flutter_learn/new_learn/lib/core/components/video_player_view.dart) |
| **ImagePreviewViewer** | 通用图片预览 — photo_view 双指缩放 + Hero 动画 | [image_preview_viewer.dart](file:///d:/flutter_learn/new_learn/lib/core/components/image_preview_viewer.dart) |
| **RichTextContent** | 富文本渲染 — HTML + audio/video 自动替换为播放器 | [rich_text_content.dart](file:///d:/flutter_learn/new_learn/lib/core/components/rich_text_content.dart) |
| **PersistentSnapSheet** | 常驻底部面板 — smooth_sheets 封装 | [persistent_snap_sheet.dart](file:///d:/flutter_learn/new_learn/lib/core/components/persistent_snap_sheet.dart) |
| **AppUpdateDialog** | 版本更新弹窗 — 强制/可选 + 平台分流跳转 | [app_update_dialog.dart](file:///d:/flutter_learn/new_learn/lib/core/components/app_update_dialog.dart) |

### 10.3 服务层封装思路（3个核心服务）

| 服务 | 封装思路 | 代码 |
|------|----------|------|
| **PickerService** | 图片选择统一服务 — Web用image_picker / 原生用微信选择器 + 权限守卫 | [picker_service.dart](file:///d:/flutter_learn/new_learn/lib/core/services/picker_service.dart) |
| **ImageProcessor** | 图片压缩 — 原生走flutter_image_compress / Web走纯Dart image包（Isolate隔离）| [image_processor.dart](file:///d:/flutter_learn/new_learn/lib/core/services/image_processor.dart) |
| **ShareService** | 分享服务 — 截图Widget渲染树→PNG→分享/存相册 | [share_service.dart](file:///d:/flutter_learn/new_learn/lib/core/services/share_service.dart) |

### 10.4 封装设计原则

1. **平台分流**：同一接口，io/web 双实现，条件 import自动选择
2. **资源释放**：所有 `TextEditingController` / `StreamSubscription` / `CancelToken` / `AnimationController` 在 `dispose` 中销毁
3. **防御性解析**：`fromJson` 兜底后端类型不稳定（`_toInt` / `_toDouble`）
4. **单一职责**：组件只管渲染，数据逻辑下沉到 Provider/Service
5. **配置驱动**：环境/品牌/主题互不依赖，全项目统一走 `AppConfig` 取配置

---

## 十一、学习路径与心得总结（~2 min）

### 11.1 推荐学习顺序

```
第一阶段：Widget 基础
  Text → Image → Input → Align → Stack → Wrap
    ↓
第二阶段：布局与列表
  List → Grid → Sliver → Responsive
    ↓
第三阶段：路由与表单
  Router → Detail → Form → Picker
    ↓
第四阶段：网络与数据
  Dio → Dio Pro → Isar Watch → Wrong Flow → OSS Upload
    ↓
第五阶段：主题与媒体
  Theme → Seed Palette → Animation → Rich Text → Audio → Share → Smooth Sheet
```

### 11.2 从前端转 Flutter 的核心思维转变

| 前端思维 | Flutter 思维 |
|----------|-------------|
| DOM 是真实节点 | Widget 是不可变配置，每帧重建 |
| 数据驱动视图（Vue/React）| setState 触发 Element 树 diff + 重建 |
| CSS 盒模型 | 约束传递模型（父给约束，子定大小）|
| 路由守卫 beforeEach | GoRouter redirect + refreshListenable |
| Pinia/Vuex 全局 store | Riverpod Provider + AsyncNotifier |
| axios 拦截器 | Dio 拦截器三件套 |
| rem/vw 适配 | ScreenUtil .w/.h/.spMin |
| 多环境 .env 文件 | --dart-define 编译期注入 |

### 11.3 本项目的技术亮点

1. **一套代码出 7 个品牌 App** — 编译期 `--dart-define` 注入品牌+环境
2. **响应式登录守卫** — Riverpod 写状态 + ValueNotifier 通知路由
3. **双方案屏幕适配** — 手机用 375 设计稿 + 平板回退原始尺寸 + 字体封顶
4. **两级主题模型** — 种子色自动生成色板 + 页面细节配置
5. **生产级 Dio 封装** — 拦截器/统一异常/重试/取消/进度
6. **OSS 客户端直传** — V4 签名 + PUT 直传 + 进度
7. **Isar 响应式数据库** — watch 驱动 UI 自动刷新
8. **28 个 Demo 全覆盖** — 从 Text 到 OSS，每个都有配套文档

### 11.4 配套文档

- Demo 文档索引：[docs/demos/README.md](file:///d:/flutter_learn/new_learn/docs/demos/README.md)
- 试卷架构设计：[docs/exam_architecture.md](file:///d:/flutter_learn/new_learn/docs/exam_architecture.md)
- 每个 Demo 都有六章结构文档：问题背景 / 运行方式 / 核心知识点 / 关键代码剖析 / 踩坑记录 / 扩展思考

---

> **结语**：Flutter 的学习不是背 API，而是理解「Widget 是配置、Element 是实例化、RenderObject 是渲染」这条主线。所有的高级用法 — 状态管理、路由守卫、主题换肤 — 都是建立在这条主线上的。本项目 28 个 Demo 覆盖了从基础组件到生产级封装的完整路径，建议大家按顺序跑一遍，每个 Demo 都有配套文档。