HaierEnergy · Flutter 学习文档
基于 HaierEnergy（海尔新能源 App，Flutter）真实项目代码梳理的体系化学习教程。
适合谁
前端（React / Vue）转 Flutter 的初学者。每个 Flutter / Dart 知识点都先给一个前端类比，再落到本项目真实代码。
项目背景
| 项 | 值 |
|---|---|
| 包名 | com.haier.energy.platform |
| Dart import 前缀 | package:haierenergy/... |
| Flutter SDK | >=3.5.0 <4.0.0（fvm 锁定 3.27.4 / Dart 3.6.2） |
| 规模 | lib/ 1118 个 Dart 文件（含 273 个生成文件） |
| 来源 | 由 uni-app 老项目迁移而来 |
| 技术栈 | Riverpod 2.6 + GoRouter 14 + Freezed 2.5 + Retrofit 4 + Dio 5 |
文档清单与阅读顺序
序号 NN 全局递增，按序号读即可。
序号 06 虽属「02-Dart基础」，但阅读顺序排在 03~05 之后—— 事件循环、Isolate、Stream 需要先理解 Flutter 单线程渲染模型才好消化。 详见
00-学习路线图的说明。
三条常用捷径
| 你的情况 | 读哪几篇 |
|---|---|
| 急着改 bug（第一天就要动代码） | 02 → 07 → 17 |
| 只想能写页面 | 01 → 02 → 08 → 10 → 11 |
| 只要接接口 | 01 → 07 → 09 |
每章结构
- 前端概念对照 —— 开篇一张表，把新知识挂到已有认知上
- 本项目真实代码 —— 标注
文件:行号+ 关键片段，可跳转核对 - 动手练习 —— 可运行的最小 Demo
- 自检清单 —— 「学完你应该能做到什么」
文档可信度约定
- 每段代码都从 HaierEnergy 当前代码核实后写入，标注
文件:行号 - 不粘贴大段代码（只给 10~20 行关键片段），避免代码改动后文档腐烂
- 该项目
docs/下另有 15 篇既有文档，其中docs/README.md有三处已过时（包名、i18n 入口、学习路径目录）。冲突时以本系列为准，详见00-学习路线图的「现有文档地图」
配套练习场
早期版本在项目里放了 lib/main_playground.dart 空白练习场，当前 checkout 已删除。需要跑 03~06 章通用 Demo 时，临时建一个同名最小入口即可（只包 MaterialApp，不包 ProviderScope / 主题 / i18n，练完删除、不要提交）：
bash
fvm flutter run -t lib/main_playground.dart把文档里的 Demo 粘进 PlaygroundPage 即可运行。其余章节的练习走 test/ 下的 widget test（当前 test/ 共 251 个测试文件，镜像 lib/ 结构）。