# 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-01~N-05 原生桥接、W-01~W-06 WebView 测试等待实施项）见同目录下的 [Flutter-OH-POC.md](./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`），修复后验证登录页恢复正常渲染。

![登录页正常渲染](images/flutter-login-page.png)

### 2.2 Flutter ↔ OHOS 原生插件往返

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

![Prefs 探针写入读回一致](images/flutter-poc-prefs-probe.png)

### 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`。

![native_scan 抛出 channel-error](images/flutter-poc-scan-probe.png)

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

![WebView 探针页正常渲染（点击加载前）](images/flutter-poc-webview-probe.png)

![WebView 探针页正常渲染（点击加载后）](images/flutter-poc-webview-success.png)

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