diff --git a/POC/Flutter-POC.md b/POC/Flutter-POC.md new file mode 100644 index 0000000..3aec35e --- /dev/null +++ b/POC/Flutter-POC.md @@ -0,0 +1,60 @@ +# 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 相关文档里显著提示。 diff --git a/POC/images/flutter-login-page.png b/POC/images/flutter-login-page.png new file mode 100644 index 0000000..1a5b30c Binary files /dev/null and b/POC/images/flutter-login-page.png differ diff --git a/POC/images/flutter-poc-prefs-probe.png b/POC/images/flutter-poc-prefs-probe.png new file mode 100644 index 0000000..6285fbb Binary files /dev/null and b/POC/images/flutter-poc-prefs-probe.png differ diff --git a/POC/images/flutter-poc-scan-probe.png b/POC/images/flutter-poc-scan-probe.png new file mode 100644 index 0000000..1c2ac56 Binary files /dev/null and b/POC/images/flutter-poc-scan-probe.png differ diff --git a/POC/images/flutter-poc-webview-appfreeze.png b/POC/images/flutter-poc-webview-appfreeze.png new file mode 100644 index 0000000..988d1ee Binary files /dev/null and b/POC/images/flutter-poc-webview-appfreeze.png differ diff --git a/POC/images/flutter-poc-webview-probe.png b/POC/images/flutter-poc-webview-probe.png new file mode 100644 index 0000000..0643db1 Binary files /dev/null and b/POC/images/flutter-poc-webview-probe.png differ diff --git a/POC/images/flutter-poc-webview-success.png b/POC/images/flutter-poc-webview-success.png new file mode 100644 index 0000000..5281689 Binary files /dev/null and b/POC/images/flutter-poc-webview-success.png differ diff --git a/POC/uniappX-poc.md b/POC/uniappX-poc.md index ee5dac9..22bf4d7 100644 --- a/POC/uniappX-poc.md +++ b/POC/uniappX-poc.md @@ -1,197 +1,133 @@ -# Continental Retail APP | uni-app / uni-app x PoC 验证结论 +# Continental Retail APP | uni-app x 鸿蒙 PoC 验证结论 -## 1. 验证说明 +## 0. 结论摘要 -本文档记录经典 uni-app 与 uni-app x（蒸汽模式）在同一业务范围下的 PoC 结果，重点判断： +> **验证范围：** 本文记录 uni-app x（蒸汽模式）在鸿蒙侧的 PoC 结果。Android 和 iOS 是工程目标平台，但本文不包含其详细验证结果；当前结果也不等同于正式生产可用。 -- 三端工程是否能构建、安装和运行 -- 常用业务能力是否可接入 -- 鸿蒙平台的问题能否被复现和定位 -- 一名前端能否独立完成维护和发布 - -验证环境：App-Android、App-iOS、App-鸿蒙；本文当前重点记录 uni-app x 鸿蒙结果。 - -## 2. 验证结果 - -### 2.1 三端工程 - -**结论：通过。** - -鸿蒙本地打包、unsigned 包构建、DevEco Studio 安装启动均已跑通，构建链路无阻塞。 - -证据： - -- ![HBuilderX 鸿蒙本地打包菜单](images/packing1.png) -- ![鸿蒙 unsigned 包构建成功](images/packing2.png) -- ![DevEco Studio 安装并启动鸿蒙 App](images/packing3.png) - -### 2.2 登录与会话 - -**结论：通过。** - -鸿蒙下 Storage 读写稳定；`onShow`/`onHide` 生命周期可用；App 从后台恢复后能够刷新过期会话，退出登录可清理存储。 - -证据： - -- ![未登录状态](images/maintain0.png) -- ![模拟登录成功](images/maintain1.png) -- ![Token 刷新](images/maintain2.png) -- ![前台恢复](images/maintain3.png) -- ![退出登录并清理存储](images/maintain4.png) - -注：当前 PoC 使用普通 Storage，正式版仍需评估鸿蒙加密存储能力。 - -### 2.3 扫码与权限 - -**结论：部分通过。** - -`uni.scanCode` 可以拉起鸿蒙扫码界面，说明扫码 API、页面调用链和相机能力接入基本可用。系统出现 `Limited access to camera`，表明相机处于受限授权状态；当前截图尚未证明二维码/条码结果回传成功，权限被回收后的二次申请也未完成验证。 - -证据： - -- ![通知权限弹窗](images/permission0.png) -- ![进入扫码界面](images/permission1.png) -- ![相机受限授权提示](images/permission2.png) - - -### 2.4 定位 - -**结论：失败/受阻。** - -`uni.getLocation({ type: 'wgs84' })` 调用后返回： - -```text -getLocation:fail Failed to get provider -``` - -虽然工程已声明 `uni-location` 和 `ohos.permission.LOCATION`，但当前 Harmony 环境没有返回可用定位 provider，未获得经纬度和精度。因此目前不能确认 uni-app x 鸿蒙定位能力可用于正式业务，需要在具备定位服务的真机上复测，并继续核对框架、插件和 Harmony 版本兼容性。 - -证据： - -- ![定位 provider 获取失败](images/location-error.png) - - -### 2.5 推送与深链 - -**结论：推送受阻，应用内深链可单独验证。** - -调用 `getPushClientId` 返回： - -```text -getPushClientId: fail -errCode: 15032 -``` - -未获得有效 Push Client ID，因此 `onPushMessage`、前后台到达、关闭态通知点击和通知深链无法形成完整验证。页面内的 query 参数跳转只能验证应用内路由承接，不能替代真实通知点击测试。 - -证据： - -- ![Push Client ID 获取失败](images/push0.png) - - -### 2.6 文件链路 - -**结论：基础链路通过。** - -相册选择能够返回临时文件路径并在应用内预览；下载能够返回 HTTP 状态码和本地临时路径，下载结果也能正常渲染。拍照、PDF/Office 外部打开和复杂 URI 兼容性仍需真机复测。 - -证据： - -- ![相册选择、下载和预览成功](images/file-chain.png) - - -### 2.7 ERP H5 - -**结论：基础链路通过。** - -本地 H5 加载和 H5 -> Native JSBridge 通信已验证。鸿蒙 WebView 注入的是 `window.__uniapp_x_`，不是常见的 `window.__uniapp_x_postMessage`，因此需要按平台做兼容判断。真实 ERP、SSO、网络环境和长期后台恢复仍需复测。 - -证据： - -- ![JSBridge 通信成功](images/js_bridge.png) - - -### 2.8 维护演练 - -**结论：需人工介入。** - -修改代码后重新本地打包鸿蒙工程，若上一次生成的工程目录仍存在，会出现无法删除旧工程的错误；必须手动清理后才能重新打包，增加了单人维护和发布成本。 - -证据： - -- ![重复打包错误](images/hbuilder-repacking-issue.png) - -## 3. 结论汇总 - -| 验证项 | uni-app x 鸿蒙结论 | 状态 | +| 验证项 | 当前结果 | 状态 | | --- | --- | --- | -| 三端工程 | 本地打包、unsigned 构建、DevEco 安装启动通过 | 通过 | +| 三端工程（鸿蒙侧构建） | 本地打包、unsigned 包构建、DevEco Studio 安装启动通过 | 通过 | | 登录与会话 | Storage、生命周期、前后台会话恢复通过 | 通过 | -| 扫码与权限 | 可拉起扫码界面；相机为受限授权，结果回传和权限恢复待验证 | 部分通过 | +| 扫码与权限 | 可拉起扫码界面；结果回传和权限恢复待验证 | 部分通过 | | 定位 | `Failed to get provider`，未获得定位结果 | 失败/受阻 | | 推送与深链 | `getPushClientId` 返回 `errCode: 15032`；应用内深链可单独验证 | 受阻 | | 文件链路 | 相册、下载、本地预览基础链路通过 | 基础通过 | | ERP H5 | 本地 H5 与 JSBridge 基础通信通过 | 基础通过 | | 维护演练 | 重复打包前需手动删除旧工程目录 | 需人工介入 | -**总体判断：** uni-app x 鸿蒙的工程构建、会话、文件和基础 WebView 链路可行；扫码已能进入系统能力，但结果和权限恢复仍需补测；定位和推送分别受到 provider 获取失败、Push Client ID 错误 `15032` 阻断，不建议在问题未明确前直接承诺正式业务可用。 +**当前状态：** 工程构建、会话、文件和基础 WebView 链路已验证；扫码已能进入系统能力，但尚未形成完整闭环；定位和推送存在明确阻塞。 -## 4. Uni-app x 开发问题 +**未闭环事项：** 扫码结果回传与权限回收后的二次申请；具备定位服务真机上的定位能力；Push Client ID、前后台消息和通知点击深链；拍照、外部文件打开、复杂 URI、真实 ERP/SSO、网络环境及长期后台恢复。 -以下问题不属于业务功能本身，但会直接影响开发效率、工具链选择和单人维护成本。 +## 1. 验证范围与说明 -### 4.1 HBuilderX AI 工具模型支持有限 +本 PoC 重点确认鸿蒙侧工程能否构建、安装和运行，常用业务能力能否接入，问题能否复现定位，以及单人维护和发布的实际成本。 -**现象：** HBuilderX 自带 AI 开发工具可选择的模型较少，目前主要只有 DeepSeek 和智谱两类模型，无法满足不同团队对模型能力、稳定性和部署方式的多样化需求。 +验证对象为 uni-app x（蒸汽模式）工程；涉及的目标平台为 Android、iOS 和鸿蒙，本文当前仅记录鸿蒙侧验证结果。 -**影响：** 团队难以统一接入现有模型账号或第三方模型服务，AI 编程工具的扩展性和可替代性有限。 +## 2. 验证结果 -证据： +### 2.1 工程与鸿蒙构建 -- ![HBuilderX AI 工具模型列表](images/hbuilder-ai-agent.png) +**结论：通过。** 鸿蒙本地打包、unsigned 包构建，以及通过 DevEco Studio 安装和启动均已跑通，当前构建链路无阻塞。 -### 4.2 HBuilderX AI 工具使用成本较高 +![HBuilderX 鸿蒙本地打包菜单](images/packing1.png) +![鸿蒙 unsigned 包构建成功](images/packing2.png) +![DevEco Studio 安装并启动鸿蒙 App](images/packing3.png) -**现象：** HBuilderX AI 工具采用订阅收费模式，套餐价格较高。 +### 2.2 登录与会话 -**影响：** 若团队多人长期使用，订阅费用会增加整体研发成本；正式引入前需要结合使用频率、额度和团队规模评估投入产出比。 +**结论：通过。** 鸿蒙下 Storage 读写稳定；`onShow`/`onHide` 生命周期可用；App 从后台恢复后能够刷新过期会话，退出登录可清理存储。当前 PoC 使用普通 Storage，正式版仍需单独评估鸿蒙加密存储能力。 -证据： +![未登录状态](images/maintain0.png) +![模拟登录成功](images/maintain1.png) +![Token 刷新](images/maintain2.png) +![前台恢复](images/maintain3.png) +![退出登录并清理存储](images/maintain4.png) -- ![HBuilderX AI 工具收费信息](images/hbuilder-ai-agent-cost.png) +### 2.3 扫码与权限 -### 4.3 鸿蒙工程重复打包需要人工清理 +**结论：部分通过。** `uni.scanCode` 可拉起鸿蒙扫码界面，扫码 API、页面调用链和相机能力接入基本可用。系统出现 `Limited access to camera`，表明相机处于受限授权状态；当前尚未证明二维码/条码结果回传成功，也未验证权限被回收后的二次申请。 -**现象：** 修改代码后重新打包鸿蒙工程时，可能无法自动删除上一次生成的工程目录；重新打包前有时需要手动删除旧工程或旧包目录。 +![通知权限弹窗](images/permission0.png) +![进入扫码界面](images/permission1.png) +![相机受限授权提示](images/permission2.png) -**影响：** 重复构建流程不够顺畅，增加了构建失败排查和单人发布的额外操作成本。 +### 2.4 定位 -证据： +**结论：失败/受阻。** 调用 `uni.getLocation({ type: 'wgs84' })` 后返回： -- ![HBuilderX 重新打包问题](images/hbuilder-repacking-issue.png) +```text +getLocation:fail Failed to get provider +``` -### 4.4 打包过程反馈不清晰 +工程已声明 `uni-location` 和 `ohos.permission.LOCATION`，但当前 Harmony 环境没有返回可用定位 provider，未获得经纬度和精度。该结果尚不能确认 uni-app x 鸿蒙定位能力可用于正式业务，需在具备定位服务的真机上复测，并核对框架、插件和 Harmony 版本兼容性。 -**现象：** 打包出错时，HBuilderX 的过程反馈不够明确；有时不会清晰提示打包是否已经结束，进度展示也不明显。 +![定位 provider 获取失败](images/location-error.png) -**影响：** 开发者难以判断当前任务是在执行、等待还是已经失败，容易重复点击或误判构建状态，降低开发体验和问题定位效率。 +### 2.5 推送与深链 -证据： +**结论：推送受阻；应用内深链可单独验证。** 调用 `getPushClientId` 返回： -- ![HBuilderX 打包过程反馈问题](images/hbuilder-repacking-issue.png) +```text +getPushClientId: fail +errCode: 15032 +``` -### 4.5 HBuilderX 插件下载收费且存在广告 +由于未获得有效 Push Client ID，`onPushMessage`、前后台消息到达、关闭态通知点击和通知深链均未形成完整验证。页面内 query 参数跳转只能证明应用内路由承接，不能替代真实通知点击测试。 -**现象：** HBuilderX 插件市场中部分插件下载需要付费，插件列表和下载页面中还存在广告内容。 +![Push Client ID 获取失败](images/push0.png) -**影响：** 团队获取所需插件能力时可能产生额外费用，广告内容也会影响开发工具的使用体验，正式引入前需评估所需插件的付费情况。 +### 2.6 文件链路 -证据： +**结论：基础链路通过。** 相册选择可返回临时文件路径并在应用内预览；下载可返回 HTTP 状态码和本地临时路径，结果也能正常渲染。拍照、PDF/Office 外部打开和复杂 URI 兼容性仍需真机复测。 -- ![HBuilderX 插件下载收费和广告](images/HbuilderX-plugin.png) +![相册选择、下载和预览成功](images/file-chain.png) -### 4.6 本章结论 +### 2.7 ERP H5 -**结论：开发工具链和鸿蒙打包体验存在明显改进空间。** +**结论：基础链路通过。** 本地 H5 加载和 H5 → Native JSBridge 通信已验证。鸿蒙 WebView 注入的是 `window.__uniapp_x_`，不是常见的 `window.__uniapp_x_postMessage`，因此实现时需要按平台做兼容判断。真实 ERP、SSO、网络环境和长期后台恢复仍需复测。 -HBuilderX 内置 AI 工具存在模型选择少、订阅成本较高的问题；鸿蒙重复打包存在旧工程清理问题，打包过程的进度和结束状态反馈也不够清晰。这些问题不会直接否定 uni-app x 的业务开发能力，但会增加团队工具成本、构建等待成本和单人维护成本，应在正式项目中纳入工具链和发布流程评估。 +![JSBridge 通信成功](images/js_bridge.png) + +### 2.8 维护演练 + +**结论：需人工介入。** 修改代码后重新本地打包鸿蒙工程时，若上一次生成的工程目录仍存在，会出现无法删除旧工程的错误；需手动清理后才能重新打包，增加单人维护和发布成本。 + +![重复打包错误](images/hbuilder-repacking-issue.png) + +## 3. 开发工具链问题 + +以下观察不属于业务功能本身，但会影响工具链选择、开发效率和单人维护成本。 + +### 3.1 HBuilderX AI 工具模型支持有限 + +**POC 观察：** HBuilderX 自带 AI 开发工具可选模型较少，当前主要为 DeepSeek 和智谱两类模型。团队难以统一接入既有模型账号或第三方模型服务，工具的扩展性和可替代性有限。 + +![HBuilderX AI 工具模型列表](images/hbuilder-ai-agent.png) + +### 3.2 HBuilderX AI 工具使用成本较高 + +**POC 观察：** HBuilderX AI 工具采用订阅收费模式，套餐价格较高。多人长期使用时会增加研发成本，正式引入前需结合使用频率、额度和团队规模评估投入产出比。 + +![HBuilderX AI 工具收费信息](images/hbuilder-ai-agent-cost.png) + +### 3.3 鸿蒙工程重复打包需要人工清理 + +**POC 观察：** 修改代码后重新打包时，HBuilderX 可能无法自动删除上一次生成的工程目录；该问题已在[2.8 维护演练](#28-维护演练)中复现。重复构建流程不够顺畅，会增加构建失败排查和单人发布的额外操作成本。 + +### 3.4 打包过程反馈不清晰 + +**POC 观察：** 打包出错时，HBuilderX 的过程反馈、结束状态和进度展示不够明确。开发者难以判断任务是在执行、等待还是已失败，容易重复点击或误判构建状态，降低问题定位效率。 + +![HBuilderX 打包过程反馈问题](images/hbuilder-repacking-issue.png) + +### 3.5 HBuilderX 插件下载收费且存在广告 + +**POC 观察：** HBuilderX 插件市场中部分插件下载需要付费，插件列表和下载页面中还存在广告内容。团队获取所需能力时可能产生额外费用，正式引入前需评估所需插件的付费情况。 + +![HBuilderX 插件下载收费和广告](images/HbuilderX-plugin.png) + +### 3.6 本章结论 + +开发工具链和鸿蒙打包体验存在改进空间。上述问题不否定已验证的业务能力，但会增加工具成本、构建等待成本和单人维护成本，应纳入后续工具链和发布流程评估。