conti-docs/POC/Flutter-POC.md

Continental Retail APP | Flutter 鸿蒙 PoC 验证结论

0. 结论摘要

验证范围： 本文记录 CPF-Flutter 维护的 Flutter OpenHarmony 适配发行版（Flutter_OH）在 OpenHarmony 模拟器上的最小化验证结果——工程构建安装、Flutter↔OHOS 原生插件双向通信、未实现原生能力的显式失败、以及 WebView 最小化探针（含 JS↔Dart 桥接往返）。本轮主动收敛范围，不含真机硬件和性能测试；当前结果不等同于正式生产可用。

验证项	当前结果	状态
工程构建、安装与首次启动	debug HAP 构建、安装、首次启动均通过，登录页正常渲染	通过
Flutter ↔ OHOS 原生插件往返	core_storage（shared_preferences_ohos）写入/读回一致	通过
未实现原生能力的显式失败	native_scan 按设计抛出 NativeScanException(code=channel-error)，非静默返回假数据	通过
WebView 最小化探针	内联 HTML／本地 HTTP 页面均可渲染，JS↔Dart 桥接往返已实现	通过
Flutter 插件生态的 OHOS 适配	已运行验证存储、WebView；官方 package 与第三方库适配清单均覆盖大量常见原生能力	本 PoC 已验证 2 项；其余为公开适配候选

当前状态： 工程构建/安装/启动链路、Flutter 与 OHOS 原生插件的基础双向通信、未实现能力的显式失败路径、WebView 最小化渲染与 JS↔Dart 桥接往返均已验证通过。存储和 WebView 两类常见 Flutter package 已在本 PoC 运行验证；官方 package 与第三方库的公开适配生态为其余常见原生能力提供了可选实现路径，但不替代项目级和真机验收。

未闭环事项： 真机硬件能力（相机扫码、定位、推送等）；签名发布与性能。更完整的验证方法论（含 N-01N-05 原生桥接、W-01W-06 WebView 测试等待实施项）见同目录下的 Flutter-OH-POC.md。

1. 验证范围与说明

本 PoC 重点确认 CPF-Flutter 的 Flutter_OH 工程能否构建、安装和运行，已接入的原生插件双向通信是否正常，以及未实现的原生能力是否按预期显式失败而非静默降级。

验证对象为 Continental Retail APP 的 Flutter 工程（harmony_3.41.9 分支）；涉及的目标平台为 Android、iOS 和鸿蒙，本文仅记录鸿蒙侧验证结果。验证环境：Flutter_OH 3.41.10-ohos-1.0.0，模拟器 127.0.0.1:5555（ohos-x64）。

本轮验证通过仓库内新增的 PocVerificationPage（app/lib/src/poc_verification_page.dart）完成，该页面仅在非 prod flavor 下从工作台 AppBar 可见，只用于产出本文的验证截图，不是正式功能。WebView 探针额外拆分为单独的临时页面 PocWebviewProbePage（app/lib/src/poc_webview_probe_page.dart），直接使用 CPF-Flutter 的 OHOS 适配版 webview_flutter（commit SHA 固定），不经过仓库正式的 core_webview 封装，验证完成后即删除。

2. 验证结果

2.1 工程构建、安装与首次启动

结论：通过。 执行仓库根目录 enable-ohos.ps1 启用 hvigorw/ohpm 工具链后，flutter build hap --debug --target-platform ohos-x64 构建通过并安装到模拟器，App 首次启动、登录页正常渲染。

此前曾出现启动白屏：根因是 packages/core_storage/pubspec.yaml 把 shared_preferences git 依赖按分支名（而非 commit SHA）固定，Windows 下 Dart pub 的本地 git 缓存复用了错误的工作树，静默 fallback 到无 OHOS 实现的托管版 shared_preferences，导致 SharedPreferencesPlugin 未注册、启动早期即挂死。修复方式是把 ref 固定为具体 commit SHA（19bd50ff6d5eaa96f18c63796c51e1b4e78a7480），修复后验证登录页恢复正常渲染。

2.2 Flutter ↔ OHOS 原生插件往返

结论：通过。 在 PocVerificationPage 中通过 core_storage 的 Prefs（包装 shared_preferences_ohos）写入一个带时间戳的探针值，再读回比对，写入值与读回值一致，证明 Flutter Dart 层与 OHOS 侧原生插件的双向通信链路正常工作。

2.3 未实现原生能力的显式失败（native_scan）

结论：通过（显式失败，但失败层级与预期不同）。 native_scan 在 Android/iOS 侧是有意保留的 TODO 桩代码，OHOS 侧完全没有桥接声明。在 PocVerificationPage 中调用 NativeScan().startScan(...) 实际抛出的是 NativeScanException(code=channel-error, message=Unable to establish connection on channel: "dev.flutter.pigeon.native_scan.ScanHostApi.startScan")——这是 Pigeon 生成的平台通道找不到任何 OHOS 端注册实现时的通道级错误，而不是应用层预先定义的 UNSUPPORTED_PLATFORM 语义错误码（OHOS 侧目前确实也没有实现任何一种 stub）。结论仍然是通过：未实现的原生能力确实显式失败并携带可诊断的错误信息，没有静默返回假数据；但如果未来要在 OHOS 侧交付一个"显式声明不支持"的体验（而非通道级异常），需要补一个轻量 OHOS stub 实现去主动抛出语义化的 UNSUPPORTED_PLATFORM。

2.4 WebView 最小化探针与 JS↔Dart 桥接

结论：通过。 本轮的临时、单文件 WebView 探针页（app/lib/src/poc_webview_probe_page.dart，直接依赖 CPF-Flutter 的 OHOS 适配版 webview_flutter/webview_flutter_ohos，commit SHA 固定，不经过仓库正式的 core_webview 封装）验证了两件事：WebView 组件能否在 OHOS 上渲染，以及最基础的 JS↔Dart 双向桥接（addJavaScriptChannel）能否工作。两种加载路径——loadHtmlString 内联 HTML、loadRequest 加载本地 HTTP 页面（app/poc_html/index.html，配合 VS Code Live Server，端口 5500）——都注册了同一个 PocBridge 通道：页面里点击「JS → Dart 桥接测试」按钮会把消息发给 Dart，Dart 收到后再调用 runJavaScript 回写页面文字，确认双向都通。两条路径均渲染正常，桥接往返符合预期。

2.5 OpenHarmony 适配的 Flutter packages

结论：常见原生能力已有成体系的适配基础；本 PoC 已实际验证其中两项。 CPF-Flutter 的 flutter_packages OpenHarmony 兼容适配项目基于 Flutter 社区 package 库提供 OHOS 实现。其公开兼容表按 Flutter 3.41 列出了多项已适配版本；适配 package 通过 Git 依赖接入，flutter pub get 后由工具链处理对应 OHOS 依赖。

能力类别	package 与公开适配版本（Flutter 3.41）	本 PoC 状态
本地 KV 存储	shared_preferences 2.5.4	已验证： 固定至 CPF-Flutter commit 19bd50ff…；shared_preferences_ohos 已注册，探针写入/读回一致
WebView / JSBridge	webview_flutter 4.13.1	已验证： 固定至 CPF-Flutter commit 89476bb…；页面渲染、JS→Dart 与 Dart→JS 往返通过
文件与系统路径	file_selector 1.1.0、path_provider 2.1.5	公开适配版本已列出；未纳入本轮运行验证
图片与相机	image_picker 1.2.1、camera 0.12.0+1	公开适配版本已列出；真机相机、权限和业务链路待验证
外部跳转与生物认证	url_launcher 6.3.2、local_auth 3.0.1	公开适配版本已列出；未纳入本轮运行验证
视频与应用内购买	video_player 2.11.1、in_app_purchase 3.2.3	公开适配版本已列出；未纳入本轮运行验证
原生接口代码生成	pigeon 26.3.4	公开适配版本已列出；当前项目锁定 26.3.1 用于 Android/iOS，OHOS ArkTS 生成链路未在本轮验证

这份适配清单说明，存储、文件、媒体、相机、认证、深链、WebView 等主流移动端能力已有明确的 OHOS package 接入路径；其中存储与 WebView 已由本项目实际运行证明。它不能证明任意第三方依赖、全部业务组合或真机硬件能力均已覆盖：每个含原生实现的 package 仍须锁定版本，并完成模拟器和目标真机验证。兼容表查询日期：2026-09-04。

2.6 OpenHarmony 适配的第三方库生态

结论：第三方库的公开适配范围广，能够覆盖大部分常见移动端能力类别；是否可用于当前项目取决于 Flutter_OH 版本匹配和项目级验证。 CPF-Flutter 的 OpenHarmony 平台 Flutter 三方库适配情况列出的“已适配”表编号为 1–262，覆盖权限、UI、设备信息、位置/地图、扫描识别、存储与文件、媒体、网络/蓝牙、安全加密、应用管理与通信等类别。

业务能力类别	已适配库示例	对本项目的意义
权限、设备与系统能力	permission_handler、package_info、device_info_plus、open_app_settings	可为权限申请、设备信息、应用设置等能力提供 OHOS 实现候选
定位、地图与扫码识别	location、geolocator、geocoding、amap_flutter_map、mobile_scanner、flutter_scankit	覆盖定位、地理编码、地图、二维码/条码等门店场景常见需求
文件、相册与打印	open_file、file_picker、photo_manager、printing、PDF 查看类库	覆盖文件选择、相册管理、外部打开、打印和文档呈现等候选能力
媒体与交互	image_picker、camera、video_player、flutter_webrtc、flutter_tts	覆盖采集、图片/视频处理、音视频和语音交互等候选能力
网络、蓝牙、安全与业务支撑	蓝牙、Wi‑Fi、HTTP、加密、推送/通知、分享、应用升级等多类库	为外设连接、网络诊断、安全处理和应用运营能力提供候选实现

版本边界： 该第三方清单按 Flutter 3.7、3.22、3.27、3.35 标注推荐版本，未提供当前 PoC 所用 Flutter_OH 3.41.10-ohos-1.0.0 的对应关系。因此，以上 262 项是生态覆盖和选型候选的证据，不是对当前 3.41 PoC 的逐库运行验证；本 PoC 已实际运行通过的适配 package 仍是本节 2.5 所列的 shared_preferences 与 webview_flutter。第三方库引入时应按其仓库 TAG 固定依赖，并在 ohos-x64 模拟器和目标 ohos-arm64 真机完成验证。清单查询日期：2026-09-04。

3. 开发工具链问题

3.1 hvigorw/ohpm 需要每个终端会话单独启用 PATH

POC 观察： hvigorw 和 ohpm 不在默认 PATH 中，每个新终端会话需要先执行仓库根目录的 enable-ohos.ps1 设置 DEVECO_HOME/DEVECO_SDK_HOME 并追加 PATH，否则 flutter build hap 会报 Failed to find hvigorw in the search path。这一步容易被遗忘，建议在 OHOS 相关文档里显著提示。