霏霏落到湃湃基于多年的 Flutter 开发经验，以及最近一年多在鸿蒙生态上折腾的心得，我来完整梳理一下“车维管家”这个项目里最核心的模块——维修状态概览——是怎么一步步从想法落到真实界面上的。这篇文章不聊虚的，重点是工程实现、状态管理、数据库选型，以及跨 Flutter 和 HarmonyOS 两个平台时那些你绕不开的适配细节。
如果你正准备做一个有点业务深度的跨端管理系统，或者正在纠结 Flutter 怎么在鸿蒙设备上跑得稳，这篇内容应该能帮你提前避开不少坑。我会把关键代码、选型理由、踩过的雷都摊开讲，希望对你有一点点参考价值。
1. 项目背景与整体设计思路
车维管家不是一个 Demo 级别的“待办事项”应用，它要服务的场景是真实的车辆维修门店管理：车主把车送进来，前台开单，技师接单维修，质检员验收，最后通知客户取车。整个过程涉及角色多、状态变化频繁、数据实时性要求高，老板还要随时看得到店里每台车现在到底修到哪一步了。
“维修状态概览”就是整个系统的交通指挥中心。它要把所有在店车辆的维修进度、工单信息、技师安排、异常滞留车辆等信息集中在一个页面上呈现出来，让门店管理者一打开 App 就能对全局一目了然。这个模块看着只是几个卡片和列表，但真正做起来，牵扯到状态机设计、跨端 UI 适配、本地缓存与远程数据同步、推送消息处理等一系列问题。
1.1 核心需求拆解
在写第一行代码之前，我先梳理了这个“状态概览”页面必须满足的几个硬性需求。这些需求直接决定了后续的技术选型和架构设计，不能含糊。
- 状态实时可见：车辆从“待接车”到“维修中”再到“待质检”“待交车”“已完成”，每一步流转都要能在概览页面上快速更新，不能出现技师那边改完状态，管理端这边还停留在旧数据的尴尬情况。
- 多维度信息聚合：一个状态卡片上不只显示“维修中”三个字，还需要展示车牌号、车主联系方式、维修项目、当前负责技师、已等待时长、进度百分比等结构化信息。这就意味着页面需要复杂的数据模型支持，而不是简单渲染一串字符串。
- 离线可用与后台同步：维修车间环境复杂，网络经常不稳定。如果完全依赖在线请求，技师在车间里更新状态时一旦断网就会卡住。我决定在“维修状态概览”里引入本地数据库，把当前工单列表缓存到本地，同时允许在后端恢复连接时自动进行增量同步。
- 快速筛选与检索：门店同时可能有几十台车在修，概览页要支持按维修状态、入场时间、技师姓名、车牌号等维度进行筛选，方便管理者快速定位异常情况。比如“有没有车在维修中已经超过三天了”，这类查询要在本地直接完成，响应速度必须足够快。
- 跨端一致性与鸿蒙适配：这个 App 的管理端需要同时运行在 Android 手机、HarmonyOS 手机，以及一部分平板上。既然选择了 Flutter 作为 UI 框架，那页面布局、字体渲染、底部安全区等细节就都要做好适配，尤其是鸿蒙环境下的生命周期管理和权限处理，和安卓有细微差别，必须单独测试。
正因为需求里有“本地数据库+后端同步”和“跨 Flutter 与鸿蒙双端”这两个硬骨头，我在技术选型上下了不少功夫，下面一节详细说。
1.2 为什么选 Flutter + HarmonyOS，而不是纯原生
其实最初团队内部争论过一阵子：是不是要用 ArkTS 写一套纯鸿蒙原生页面？后来综合评估了几个维度，还是定了 Flutter。
第一，车维管家本身就不只面向鸿蒙设备，门店前台用的安卓平板、老板手机上的 iOS 版、还有后续可能扩展的 Windows 桌面端，都需要同一套核心代码。如果每个平台都写原生实现，光维护三套 UI 逻辑和状态代码就已经让人崩溃了。Flutter 在这件事上的优势非常明显：一套 Dart 代码，渲染逻辑自绘，理论上可以覆盖移动端和桌面端。
第二，Flutter 的渲染引擎是自绘的，这意味着在鸿蒙设备上，它的 UI 表现和安卓端可以做到高度一致，不会因为系统控件差异出现样式错乱。这对“维修状态概览”这种有大量自定义卡片、进度条、状态色块的界面来说，省了很多适配功夫。
第三，从团队技术栈角度看，我们团队本来就有 Flutter 开发经验，而鸿蒙原生 ArkTS 的学习曲线并不平缓。既然业务核心是打通门店管理流程、快速验证产品价值，那选择 Flutter 能让我们把精力聚焦在业务逻辑而不是重复造轮子上。
当然，选择 Flutter 也意味着要面对兼容性问题。比如鸿蒙系统对 Flutter 引擎的接入支持、第三方插件是否适配鸿蒙 OpenHarmony 接口、动态权限管理差异等，这些都需要在工程搭建阶段提前处理。我在后面专门有一节写鸿蒙适配的具体过程。
1.3 整体架构设计：模块化与数据流
为了让“维修状态概览”这个页面不至于随着功能增加变成一个大泥球，我在项目初始化时就把架构划分清楚。整体采用的是分层架构，从下到上分别是数据层、仓库层、状态管理层和 UI 层。每一层的职责单一，不会越界。
数据层主要封装 HTTP API 接口调用和本地数据库操作。网络请求用的是 dio，本地数据库用的是 sqflite。仓库层则负责数据来源的切换，如果本地有缓存就直接读缓存，同时发起后台更新；如果本地没有数据，就先拉远程接口写入缓存再返回给上层。
状态管理层我选的是 Riverpod。为什么不选 Provider 或者 Bloc？这里展开说一下。车维管家这个“状态概览”页面的数据流相当复杂：有实时状态推送、有筛选条件变化、有本地数据库查询结果回调，还有用户手动下拉刷新动作。Riverpod 的响应式状态管理和便捷的异步状态处理能力，能让我用比较少的样板代码把各类状态源组合起来。再加上它天然支持自动销毁、依赖注入，写单测也很方便，中期维护压力会小很多。
UI 层就纯粹了，只用 StatelessWidget 和 ConsumerWidget 来展示状态，不直接和数据库或网络层打交道。这样后续如果要换 UI 框架或者调整页面结构，底层逻辑都能保持稳定。
这个架构设计为后续的“维修状态概览”实现打好了地基。接下来会讲工程环境的搭建，尤其是 Flutter 在鸿蒙环境下的坑，这部分绝对能帮你省下半天调试时间。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 环境搭建与鸿蒙适配实录
很多人在 Flutter 上跑鸿蒙设备时最容易卡住的就是环境这一步。我先把完整流程和关键配置梳理一遍。
注意，下面写的是我当时实际操作的记录，不同版本的 SDK、Flutter SDK 和 IDE 可能会导致步骤略有差异，但整体思路不变。
2.1 开发环境版本说明
先说版本搭配，因为 Flutter 对鸿蒙的适配是渐进式的，老版本很可能遇到编译不过或者运行崩溃的问题。
- Flutter SDK：3.13.0 以上，理论上越新越好，因为 OpenHarmony 的 Flutter 适配补丁一直在更新。
- Dart SDK：随 Flutter 内置，不需要单独安装。
- HarmonyOS SDK：我使用的是 API 9 的版本，华为 DevEco Studio 可以管理。
- 操作系统：Windows 11 64 位，开发的是安卓端和管理端共存的场景，同时装了一个鸿蒙 4.0 模拟器作为测试环境。
- 编辑器：VS Code 为主，配了 Flutter 和 Dart 插件；偶尔也用 Android Studio 处理原生工程相关的问题。
如果你的 Flutter 版本比较旧，建议在项目里开启自动升级，或者手动更换到新版本，否则后续在鸿蒙真机上跑时会碰到很多奇怪的 C++ 编译错误。
2.2 Flutter 环境变量配置与常见报错
很多新手在刚装好 Flutter 时会忽略一个细节：环境变量 PATH 的修改需要新开一个终端窗口才能生效。我见过好几个同事装完之后在旧终端里执行 flutter doctor，结果提示找不到命令，还以为是安装失败了。所以装完 Flutter 后，务必关掉终端重新打开一遍。
配置好环境之后，建议依次执行：
bash复制flutter doctor
flutter config --enable-ohos
第一个命令检查基本环境，第二个命令是启用 OpenHarmony 平台支持。如果你用的是比较新的 Flutter 版本，可能不需要这个操作，但保险起见还是执行一下。
如果在 flutter doctor 里看到 Android toolchain 报错，先确认 Android SDK 路径对不对。特别是 Windows 环境，经常因为环境变量里的路径带空格导致 Gradle 找不到 SDK。建议把 Android SDK 的路径配置在 local.properties 文件里，而不是只依赖系统环境变量。
properties复制sdk.dir=C\:\\Users\\你的用户名\\AppData\\Local\\Android\\Sdk