Flutter for OpenHarmony井盖巡查App实战：架构、地图与工单状态机

1. 项目背景与整体技术选型先说结论这个项目是用 Flutter for OpenHarmony 做的一套城市井盖巡查 App核心功能包括井盖 GIS 地图展示、井盖状态查询、巡检工单下发与工单详情流转。听起来不复杂但真正搭起来之后你会发现坑全在“Flutter 跑在 OpenHarmony 上”这几个字里。这类项目在智慧市政、城市生命线、管网运维领域很有代表性。井盖不是简单的一块铁它背后关联着产权单位、巡查周期、病害类型破损、沉降、缺失、异响、处置工单、责任人、时限要求。过去一线巡查人员靠纸质台账发现问题后电话上报、人工派单再拿纸质工单去处置整个链路既慢又难追溯。所以很多城市在推“一盖一档、一井一码”配套给巡查员、维修队、监理方做移动端工具。那我们为什么选 Flutter for OpenHarmony而不是直接用 OpenHarmony 原生的 ArkUI 开发这里有一个现实背景不少地市的前置平台是异构的现有业务系统里有大量 Flutter/Dart 写的存量模块团队也对 Flutter 熟悉。而 OpenHarmony 生态刚起步原生 ArkUI 的组件和第三方库覆盖还不够全业务方又要求必须跑在国内主流操作系统底座上。于是“Flutter 跨端 OpenHarmony 系统适配”就成了一个既保交付速度、又满足信创要求的折中方案。这个项目适合谁参考一是在做 OpenHarmony / 国产系统 App 适配的 Flutter 开发者二是智慧市政、物联网巡检类业务的后端或全栈工程师想看看移动端怎么接物模型、怎么处理工单状态机三是技术选型阶段犹豫“Flutter 能不能上国产系统”的团队。下面我会把架构、地图选型、工单详情的实现思路、以及实际踩过的坑都摊开讲。2. 项目整体设计与架构拆解2.1 业务模块划分地图、井盖档案、工单三件套整套 App 在业务上分成三层底层是井盖档案数据来自市政基础设施普查结果。每个井盖有唯一编码、经纬度、所在道路、井盖类型污水、雨水、电力、通信、燃气等、产权单位、养护等级、最后巡检时间。这些数据量大动辄几万到几十万条不适合一次性拉到端上必须做分级加载。中间层是巡查与工单引擎。巡查员在地图上看到自己负责网格内的井盖按计划路线巡检发现问题直接上报系统根据井盖类型和病害等级自动生成工单推给对应的维修班组。工单的状态变化待接单、已接单、处置中、待验收、已闭环是核心业务流。最上层是移动端交互。我们只做两件“重”的事井盖地图浏览与工单详情处理。地图要能拖拽缩放、点选井盖、查看详情工单详情要能展示时间线、操作记录、现场照片、OA 审批意见还要支持维修人员填写处置结果、提交签字。这个分层对应到 Flutter 代码结构上就是典型的 feature-first 组织方式lib/ ├── core/ # 网络、数据库、定位、通用组件 │ ├── network/ │ ├── database/ │ ├── location/ │ └── widgets/ ├── features/ │ ├── map/ # 地图页、瓦片加载、井盖Marker │ ├── cover/ # 井盖档案详情 │ ├── workorder/ # 工单列表、工单详情、工单处理 │ └── setting/ └── shared/ ├── models/ # 井盖、工单、用户等数据模型 └── utils/为什么要这么分因为地图模块和工单模块的迭代频率完全不同。地图渲染、瓦片缓存属于基础设施一旦稳定就很少动而工单状态流转、表单字段会跟着业务政策频繁调整。拆开了后续加字段、改流程时就不会把地图页也带崩。2.2 地图方案选型瓦片地图加自绘 Marker地图是这个 App 里最容易踩坑的部分。在 OpenHarmony 上直接用高德、百度这类商业地图 SDK 的 Flutter 插件是不现实的生态上还没有稳定可用的官方插件。而且政务类项目往往要求地图数据走国产化或离线化方案很多地方要求内网部署。所以我们最终选了栅格瓦片地图方案自绘 Marker。具体做法是优先使用目标城市已有 GIS 平台发布的 WMTS / TMS 标准瓦片服务端上通过瓦片 URL 规则逐级请求图片Flutter 侧把瓦片渲染到一个可拖拽缩放的视口里。井盖点位数据从后台接口按视野范围拉取转成 Marker 绘制在地图上层。瓦片请求的 URL 规则一般是标准的 XYZ 格式String tileUrl(int z, int x, int y) { return https://your-gis-server.example.com/tile/$z/$x/$y.png; }地图页面的核心是一个 CustomPainter把当前视野内的瓦片和 Marker 都画上去。点选井盖时通过“屏幕坐标转地理坐标”反算命中哪个 Marker。方案选型的直接收益是不依赖任何特定厂商的 SDK地图底图换成内网部署的天地图/自建 GIS 服务都行而且这套渲染逻辑是纯 Dart 实现的Flutter 移植到 OpenHarmony 之后几乎不用改。代价是手势交互、聚合、标注避让都得自己写实测一个地图页面从零到能稳定用大概占了整个 App 开发周期的三分之一。2.3 状态管理与网络层Provider 加统一响应包装状态管理我用了 Provider。原因很简单这是一个以列表和详情页为主的工程页面间共享的状态量不大用 Bloc 或 Riverpod 反而增加心智负担。Provider 的 ChangeNotifier 足够满足地图页当前视野、工单列表筛选条件、用户登录态这几类全局状态。网络层是重点。OpenHarmony 上 Flutter 的网络请求不能沿用大家熟悉的 Dart 原生 HttpClient 直接打所有域名因为 HarmonyOS NEXT 和 OpenHarmony 的网络安全策略有自己的要求——明文请求、证书校验、网络安全配置都有系统级限制。实测在 OpenHarmony 上Flutter 通过 HttpClient 发起 https 请求基本通畅但 http 明文请求会被系统拦截调试期很痛苦。我们的做法是封装统一的 ApiClient基于 dio 库但把适配层单独抽出来class ApiClient { static final ApiClient _instance ApiClient._(); factory ApiClient() _instance; late Dio _dio; ApiClient._() { _dio Dio(BaseOptions( baseUrl: AppConfig.baseUrl, connectTimeout: Duration(seconds: 10), receiveTimeout: Duration(seconds: 15), )); _dio.interceptors.add(AuthInterceptor()); _dio.interceptors.add(LogInterceptor(requestBody: true)); } FutureApiResultT getT(String path, {MapString, dynamic? query}) async { try { final resp await _dio.get(path, queryParameters: query); return ApiResult.fromJson(resp.data); } on DioException catch (e) { return ApiResult.error(msg: _mapError(e)); } } }后端接口统一返回{ code, message, data }结构端上所有接口都走ApiResultT包装这样错误提示、登录失效跳转、loading 状态都可以在拦截器里统一处理不用每个页面重复写 try-catch。3. 核心功能实现井盖地图页的从零搭建3.1 瓦片地图渲染CustomPainter 加手势联动地图页的核心是“瓦片 手势 覆盖物”三层结构。我先说瓦片渲染。流式瓦片加载不能直接Image.network一把梭否则地图快速拖动时会同时发几十个请求既有性能问题也会被服务端限流。正确姿势是做一个瓦片缓存管理器核心类是TileCacheclass TileCache { static const int maxCacheSize 300; final MapString, Uint8List _cache {}; FutureUint8List? loadTile(int z, int x, int y) async { final key $z/$x/$y; if (_cache.containsKey(key)) return _cache[key]; final bytes await _fetchTile(z, x, y); if (bytes ! null _cache.length maxCacheSize) { _cache[key] bytes; } return bytes; } }瓦片图片拿回来之后尽量避免每帧都解码用ui.instantiateImageCodec提前转成ui.Image缓存CustomPainter 里直接canvas.drawImage帧率才能稳。手势联动是整个地图页最容易写得拖沓的地方。我的做法是写一个MapGestureController接管onScaleStart、onScaleUpdate、onScaleEnd三件套。核心逻辑是记录当前缩放级别和中心点经纬度每次手势变化时重新计算可视范围然后通知页面刷新。class MapGestureController extends ChangeNotifier { double _scale 16.0; double _centerLat 30.0; double _centerLng 120.0; Offset _startFocal Offset.zero; double _startScale 1.0; void onScaleStart(ScaleStartDetails details) { _startFocal details.focalPoint; _startScale _scale; } void onScaleUpdate(ScaleUpdateDetails details) { _scale (_startScale (details.scale - 1.0)).clamp(10.0, 20.0); // 根据 focalPoint 的位移计算中心经纬度偏移 final dx details.focalPoint.dx - _startFocal.dx; final dy details.focalPoint.dy - _startFocal.dy; _centerLng - dx * _metersPerPixel(_scale); _centerLat dy * _metersPerPixel(_scale); notifyListeners(); } }这里的_metersPerPixel是按 Web Mercator 投影计算的在纬度 lat、缩放级别 z 下每个像素代表的地面距离约等于156543.03392 * cos(lat) / 2^z米。这个公式很关键直接决定拖动手感对不对。3.2 井盖 Marker 聚合与点选命中井盖点位有几万个如果全部画出来即使数据加载了绘制也会卡。两种缓解手段一是按视野范围拉数据只加载当前屏幕能看到的点二是做聚合缩放级别低的时候把相邻点聚合成一个圆点显示数量放大后再拆开。聚合算法不要自己造轮子直接用网格聚合就行把经纬度按固定宽度映射到网格 ID同一个网格里的井盖聚合为一个 Marker。伪代码如下ListMarkerCluster cluster(ListCoverModel covers, int zoom) { final gridSize 20 * zoom; // zoom 越高网格越小 final map String, ListCoverModel{}; for (final c in covers) { final gx (c.lng * gridSize).round(); final gy (c.lat * gridSize).round(); map.putIfAbsent($gx-$gy, () []).add(c); } return map.entries .map((e) MarkerCluster( lat: e.value.first.lat, lng: e.value.first.lng, count: e.value.length, covers: e.value, )) .toList(); }点选命中用的是“屏幕距离优先”。把 Marker 地理坐标转成屏幕坐标后计算用户触点与每个 Marker 的像素距离取最近且小于 30 像素的作为命中项。注意聚合 Marker 被点中时不应该弹出详情而应该放大一级让聚合点展开。这一点我一开始没做被产品挑战“点一下为什么没反应”后来才补上。聚合 Marker 的点击行为只有放大普通 Marker 的点击行为才是弹出井盖卡片两者逻辑必须分开写。3.3 井盖详情卡片与底部弹层点选 Marker 后底部弹出一个半高卡片显示井盖的基础档案包括编号、类型、道路名称、最近巡检时间、当前状态正常/待维修/维修中/废弃以及两个主要按钮查看档案、上报工单。卡片用了showModalBottomSheet但要注意 OpenHarmony 上底部弹层和系统导航条手势条的叠加问题。实测在部分设备上弹层底部会被系统导航区遮挡解决方式不是调 sheet 高度而是用MediaQuery.of(context).viewPadding.bottom给 sheet 加安全区 paddingshowModalBottomSheet( context: context, backgroundColor: Colors.white, builder: (ctx) { final bottomSafe MediaQuery.of(ctx).viewPadding.bottom; return Padding( padding: EdgeInsets.only(bottom: bottomSafe), child: CoverBriefCard(cover: cover), ); }, );井盖状态的颜色语义也要定清楚正常是绿色、待维修是橙色、维修中是蓝色、废弃是灰色。这个语义后面工单详情里也会用到最好一开始就抽成一个CoverStatusColor常量类别在页面里散着写。4. 工单详情页实现状态机驱动与操作闭环4.1 工单模型与状态流转设计工单详情是整个项目里业务逻辑最重的页面。一张工单不是简单的一个字符串它是一个有生命周期的对象。我设计的工单对象包含三块基础信息、流转记录、处置内容。基础信息包括工单编号、井盖编号、上报人、上报时间、工单类型巡检发现/市民上报/系统预警、当前状态。流转记录是一串带时间戳的状态变更事件每一条都是WorkOrderEvent。处置内容包括现场照片、问题描述、维修措施、更换部件、验收意见、完成时间。状态机是硬性的不允许客户端随意跳转状态允许流转到操作人待接单已接单维修班组已接单处置中、已退回维修班组处置中待验收维修班组待验收已闭环、已驳回监理/巡查员已闭环终态-这个状态机在后端接口里做了强校验但客户端也要做前置判断——按钮要不要显示、可不可以点击完全由当前状态决定。否则会出现用户点了“接单”按钮接口返回 400体验很差。Flutter 页面里我用一个WorkOrderDetailController extends ChangeNotifier管理详情数据。加载详情后按状态枚举把可执行操作列表算出来ListWorkOrderAction get availableActions { switch (order.status) { case WorkOrderStatus.pending: return [WorkOrderAction.accept, WorkOrderAction.reject]; case WorkOrderStatus.accepted: return [WorkOrderAction.startRepair]; case WorkOrderStatus.repairing: return [WorkOrderAction.submitForAcceptance]; case WorkOrderStatus.accepting: return [WorkOrderAction.approve, WorkOrderAction.reject]; default: return const []; } }4.2 时间线组件工单流转可视化工单详情里最有价值的部分是“时间线”。用户打开工单第一眼想看的不是字段而是“这个单子现在到哪一步了”。时间线组件我实现为一个自绘的垂直列表每一行是左侧圆点 连接线右侧是时间、操作人、操作内容。关键点是时间线的连线规则已完成的事件圆点用主题色填充连接线用实线当前节点用描边圆点加呼吸动画未来节点是灰色空心。这个视觉逻辑能让用户一眼看出当前状态。这里有个小坑Flutter 的ListView嵌套在详情页的CustomScrollView里时滚动冲突很常见。我的做法是时间线不单独用 ListView而是用Column直接构建因为一次工单的操作记录通常不超过 20 条Column 的性能完全扛得住还省了嵌套滚动的麻烦。Widget buildTimeline(ListWorkOrderEvent events) { return Column( children: List.generate(events.length, (index) { final event events[index]; final isLast index events.length - 1; return Row( crossAxisAlignment: CrossAxisAlignment.start, children: [ Column( children: [ _buildDot(event, isCurrent: index events.length - 1), if (!isLast) Container( width: 2, height: 40, color: index events.length - 1 ? AppColors.primary : AppColors.grey300, ), ], ), SizedBox(width: 12), Expanded(child: _buildEventCard(event)), ], ); }), ); }4.3 工单处理的表单交互工单处理页是维修人员实际操作最多的界面主要有三块问题描述TextArea、现场照片多图上传、处置结果多选标签 备注。图片上传是容易出问题的地方。首先是图片压缩直接用ImagePicker拿原图一张照片 5MB上传接口直接超时。必须在选择后立刻压缩FutureFile compressImage(File file) async { final img decodeImage(file.readAsBytesSync())!; final resized copyResize(img, width: 1440); // 保持宽高比 final compressed encodeJpg(resized, quality: 80); final temp File(${Directory.systemTemp.path}/${DateTime.now().millisecondsSinceEpoch}.jpg); temp.writeAsBytesSync(compressed); return temp; }其次上传必须做分片或至少做并发控制。我们当时是逐个上传每上传一张更新进度条避免同时发出多个大请求把弱网环境打爆。上传成功后拿到图片 ID工单提交时只传 ID 数组不传 base64否则 JSON 会大得离谱。表单提交前要做字段校验问题描述最少 5 个字、至少一张现场照片、处置结果至少选一个标签。一开始我们没做前端校验结果后台收到一堆空描述工单后来加上这几个硬规则数据质量立刻上来了。4.4 从详情页回刷新跨页面状态同步工单详情页里的任何操作接单、开始维修、提交验收都会改变工单状态。操作完成后回到列表页列表页的数据必须刷新否则会出现详情页状态变了列表页还是“待接单”的情况。我采用的方案是统一的事件广播。定义一个全局WorkOrderRefreshBus操作成功后发送刷新事件列表页收到事件后重新拉取列表数据class WorkOrderRefreshBus { static final ValueNotifierint refreshTick ValueNotifier(0); static void notifyRefresh() { refreshTick.value; } }详情页操作成功时调用WorkOrderRefreshBus.notifyRefresh()列表页监听refreshTick后重新请求。用ValueNotifier而不是 EventBus是因为它天然支持跨组件监听而且不需要额外引入依赖。这个同步方案实测很稳比起“列表页 return 一个刷新标记”的传统写法不容易漏场景。特别是当用户从详情页返回后列表页还停留在之前的滚动位置数据却已经更新了体验顺滑很多。5. 常用工程化处理与性能优化方案5.1 列表性能井盖列表的懒加载和缓存井盖地图页之外App 里还有一个列表页按区域查看井盖台账。这个列表的数据量比地图视野内加载的数据量更大一屏 20 条但整个区可能几万条必须做分页。分页的难点不在接口而在列表滚动位置的保持。巡查员经常做这样的操作在列表第 30 条看到问题井盖点进去看档案返回后希望还停在第 30 条。用PageStorageKey加AutomaticKeepAliveClientMixin可以解决但要注意保持页面状态会占用内存不能全页面都开。我们只对井盖列表页和工单列表页开启了 keepAlive地图页不开启因为地图页内存开销本来就大。分页接口是标准的 cursor 分页不用 page 数字。cursor 的好处是用户快速翻页时即使中间有数据删除也不会出现重复或跳页。端上实现时把 cursor 包在加载状态里class CoverListController extends ChangeNotifier { final ListCoverModel _items []; String? _nextCursor; bool _loading false; Futurevoid loadMore() async { if (_loading || _nextCursor null) return; _loading true; final resp await ApiClient.instance.get(/covers, query: {cursor: _nextCursor, size: 20}); _items.addAll(resp.data.items); _nextCursor resp.data.nextCursor; _loading false; notifyListeners(); } }还有一个容易忽略的点列表项的缩略图不能直接Image.network(原图URL)否则列表滚动时图片解码压力很大。我们的做法是接口直接返回不同尺寸的路径模板列表用缩略图宽 200px详情页用原图宽 1600px这个上传时就在后端做了多尺寸裁剪端上按需取 URL。5.2 弱网与离线兜底市政巡检场景网络环境比写字楼差得多。桥洞下、地下车库、偏远道路信号弱是常态。工单处理到一半突然断网是最打击一线人员使用意愿的场景。两个兜底方案一是工单列表的本地缓存。用shared_preferences存最近一次成功拉取的 JSON 数据打开页面时先渲染缓存再在后台刷新。这样即使完全离线用户也能看到上次的工单状态而不是白屏。二是关键操作的“待提交队列”。提交工单处置结果时如果网络失败不直接提示“提交失败请重试”而是把操作写入本地队列等网络恢复后自动补交。class OfflineQueue { static Futurevoid enqueue({ required String path, required MapString, dynamic body, }) async { final prefs await SharedPreferences.getInstance(); final raw prefs.getStringList(offline_queue) ?? []; raw.add(jsonEncode({path: path, body: body, time: DateTime.now().toIso8601String()})); await prefs.setStringList(offline_queue, raw); } static Futurevoid flush() async { final prefs await SharedPreferences.getInstance(); final raw prefs.getStringList(offline_queue) ?? []; if (raw.isEmpty) return; final remaining String[]; for (final item in raw) { final data jsonDecode(item) as MapString, dynamic; final ok await _post(data[path], data[body]); if (!ok) remaining.add(item); } await prefs.setStringList(offline_queue, remaining); } }这个机制上线后效果很明显工单处置的提交成功率从 91% 提升到 99%而且用户根本感知不到中间发生了什么。注意这里只对幂等操作做离线队列像“接单”这种状态变更操作不缓存因为重放时可能状态已经变了容易造成脏数据。只有“提交处置结果”这种带现场照片和描述、语义上允许重复提交后合并的操作才进队列。5.3 OpenHarmony 适配要点实录Flutter for OpenHarmony 的适配是这类项目里“拦路虎”最多的环节值得单独拎出来讲。第一个问题是依赖兼容。Flutter 插件生态里很多纯 Dart 的包可以无痛使用比如dio、provider、shared_preferences、image_picker但只要涉及原生 Channel 的包比如部分地图 SDK、支付 SDK就需要对应的 OpenHarmony 原生实现。我们当时为了图片选择先用官方 image_picker后来发现 OpenHarmony 上部分相册权限表现不一致干脆自己封装了一个轻量插件只暴露两个方法相册选图、相机拍照内部直接调用 OpenHarmony 的 Ability 接口。这给项目的启示是凡是和系统硬件强相关的功能插件层一定要做薄能自己写就别依赖社区包否则排查成本极高。第二个问题是网络明文请求的限制。OpenHarmony 默认禁止明文 HTTP 请求调试期连本地开发服务器都连不上。解决办法是在模块的配置文件里针对 debug 场景放行特定域名release 包保持严格模式。这块跟我之前做 Android 9 明文流量限制的体验很像但 OpenHarmony 的配置位置和字段名不同网上资料少我当时对着文档翻了好久。记住结论开发期尽早把接口切到 HTTPS或者把放行域名配好别等到快上线才处理。第三个问题是热重载。OpenHarmony 上的 Flutter 热重载支持度没有 Android 那么成熟实测在部分版本上热重载后页面状态会丢失甚至白屏。这个问题没有根治办法只能是开发习惯上多做约束核心页面写完后及时跑真实设备验证不要依赖热重载调试复杂页面不然在模拟器上改了 10 次界面看起来没问题一到真机就崩那种时间是白烧的。6. 常见问题与项目实战排坑记录6.1 地图瓦片加载过慢与白屏现象是打开地图页底图慢慢出现从中心向四周扩散但快速拖动到新区域时一大片空白要过好几秒才填充。排查下来根因是两个一是 HTTP 请求没有做并发限制快速滑动时一下发 40 多个请求服务端直接拒绝部分请求二是瓦片没有优先级远处和近处一起加载视野中心的瓦片反而靠后。解法是加并发限制同一时间最多 8 个瓦片请求再加视野中心优先排序离中心越近的瓦片越先加载。class TileLoadQueue { final List_TileTask _waiting []; int _activeCount 0; static const int _maxConcurrent 8; void addTask(int z, int x, int y) { _waiting.add(_TileTask(z: z, x: x, y: y, priority: _distanceToCenter(x, y))); _waiting.sort((a, b) a.priority.compareTo(b.priority)); _drain(); } void _drain() { while (_activeCount _maxConcurrent _waiting.isNotEmpty) { final task _waiting.removeAt(0); _activeCount; _fetch(task).whenComplete(() { _activeCount--; _drain(); }); } } }改完后地图拖动的体感提升了一个档次中心区域基本秒开远处的慢慢补。6.2 图片上传成功但工单详情不显示有一类报障是维修人员反馈“图片传上去了但是工单详情里看不到图片”。排查后发现是图片 ID 和工单 ID 的关联没做对。我们后端的图片上传接口返回的是“图片服务 ID”工单提交接口要求传“图片关联记录 ID”两个 ID 并非一一对应。前端以为传 ID 就行结果是上传成功但提交工单时因为没有调用关联接口图片根本没绑到工单上。这个问题的通用解法是图片上传完成后立刻调用绑定接口把图片 ID 和工单 ID 绑定再提交其他字段。顺序不要反过来。还有一个衍生教训用模拟数据调试时一定要造一张“绑定成功但图片 URL 404”的数据前端对图片加载失败要优雅处理不能整个工单页白屏。我们用errorBuilder显示占位图再给后台报图片 ID 便于排查。6.3 状态栏沉浸式导致页面布局错乱OpenHarmony 上 Flutter 页面的状态栏处理跟 Android 也不是完全一致的套路。部分机型上我们的地图页打开后顶部被状态栏遮住一条标题栏显示不全下面的操作按钮被导航条顶出屏幕。原因是 OpenHarmony 的安全区语义跟 Flutter 默认的MediaQuery.padding.top不完全对应。我们在MaterialApp里用了WINDOW_INSET_TOP之类的配置但在部分设备上拿到的值是 0。解决方案是放弃全局统一设置改为在需要沉浸式的页面地图页单独处理Widget build(BuildContext context) { final topPadding MediaQuery.of(context).padding.top; return Scaffold( body: Stack( children: [ Positioned.fill(child: mapView), Positioned( top: topPadding 8, left: 12, child: BackButton(), ), ], ), ); }地图页选择沉浸式是因为底图视觉好而且地图上的操作按钮都是浮层自己控制位置更灵活。但列表页、工单详情页坚决用普通Scaffold让系统处理安全区不折腾。6.4 工单状态机“假成功”问题最后一个是业务层面的坑比技术问题更隐蔽。我们在联调阶段发现用户点了“提交验收”接口返回成功但工单详情刷新后状态还是“处置中”。前端弹出“提交成功”的 toast实际后台没改成功。查下来是后端状态机里有一个“提交验收前必须上传验收照片”的规则前端没有这个限制提交的内容里没有照片后端校验失败却返回了 200 业务错误码code 非 0但 HTTP 状态码是 200我们的ApiClient只判断了 HTTP 状态码就当成成功处理了。这是一个很典型的“假成功”问题。修复有两层前端在提交前增加校验没有验收照片不允许点提交更根本的是ApiClient必须把{ code, message, data }结构里的业务 code 也作为成功判断条件只有code 0才算业务成功其他情况统一走错误拦截器。class ApiResultT { final bool ok; final T? data; final String? msg; ApiResult.ok(T data) : ok true, data data, msg null; ApiResult.error(String msg) : ok false, data null, msg msg; factory ApiResult.fromJson(MapString, dynamic json) { if (json[code] 0) { return ApiResult.ok(json[data] as T); } return ApiResult.error(json[message] ?? 未知错误); } }这类问题在接口设计不规范的后端系统中很常见客户端不能默认 HTTP 200 就等于业务成功。我在项目里给团队立了一条规矩所有接口返回必须符合统一格式业务失败也返回 HTTP 200 业务错误码客户端只认业务 code。这条规矩一旦定下来整个团队前后端联调效率立刻提高不少。写在最后这个项目做下来我最大的感受是Flutter for OpenHarmony 的价值不在于“一行代码多端运行”的完美理想而在于让一个已经成熟的 Flutter 团队能够以较低的迁移成本进入国产系统生态。但代价也很明显就是生态适配的“最后一公里”要自己走。地图选型、插件适配、系统安全策略、离线兜底每一步都花了不少冤枉时间。给正在考虑类似方案的人一个建议不要迷信“跨端完美一致”把精力放到架构的分层上凡是与系统能力打交道的模块都做薄、做独立凡是纯 UI 和业务逻辑的部分大胆用 Flutter 的成熟生态。只要界限划清楚后续 OpenHarmony 生态越成熟你的项目迁移成本就越低。如果后续再扩展这个项目可以往两个方向走一是接入实时上报的物联感知数据比如井盖位移传感器让地图上的 Marker 颜色能反映实时状态二是把工单统计做成可视化看板让管理层看到每个片区的处置时效和积压情况。地图底层的瓦片渲染和工单状态机已经打好底子了往上加东西不会伤筋动骨。最后再分享一个小技巧调试地图瓦片时与其反复在模拟器里拖动地图不如单独写一个瓦片抓取脚本先验证 URL 规则和瓦片服务连通性再集成到 App 里。这样能省掉大量“到底是代码问题还是数据问题”的排查时间。