conti-docs/POC/Flutter-POC.md

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

0. 结论摘要

验证范围： 本文记录 Flutter_OH（Flutter 官方鸿蒙分支）在 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 最小化渲染与 JS↔Dart 桥接往返均已验证通过。

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

1. 验证范围与说明

本 PoC 重点确认 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 回写页面文字，确认双向都通。两条路径均渲染正常，桥接往返符合预期。

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 相关文档里显著提示。