conti-docs/POC/Flutter-OH-POC.md

Flutter_OH（OpenHarmony）适配 POC 验证报告

文档状态： 部分实施；OHOS 工程生成与 debug HAP 构建已通过

验证范围： 现有 Flutter Android / iOS App 基线 → harmony 分支 → OpenHarmony 模拟器

结论边界： 本轮没有真机。本文只用于判断开发、构建、业务代码复用和集成路径的可行性；不得将模拟器结果表述为鸿蒙生产可用或真机功能已验证。

修订历史

| 版本 | 日期 | 状态 | 说明 | | --- | --- | --- | | 0.1 | 2026-09-02 | POC 方案已冻结 | 定义范围、验收矩阵、证据要求及决策规则，实施后持续回写实际结果 | | 0.2 | 2026-09-02 | 部分通过 | 记录 Flutter_OH 3.41.10-ohos-1.0.0 / Dart 3.11.5 的依赖解析和默认 main.dart debug HAP 构建通过；确定首期 ArkTS 采用宿主 entry MethodChannel 路径 |

0. 结论摘要（实施后填写）

0.1 本 POC 回答的问题

本 POC 不回答抽象的“Flutter 能不能做鸿蒙”，而基于 Continental Retail APP 已可运行的 Android / iOS Flutter 基线，回答以下可交付的问题：

1. 能否用 Flutter_OH 在 OpenHarmony 模拟器上完成工程生成、构建、安装、启动和调试？
2. 当前 Dart 业务层、Flutter UI、状态管理、网络、路由和 H5 容器能复用多少；哪些部分必须做 OHOS 专项适配？
3. Dart 公共 API → App 宿主 entry → ArkTS 的原生能力链路是否可实现；当前 native_* facade 是否适合接入 OHOS？
4. 嵌入 H5 的 WebView / JSBridge 容器能否按现有协议工作？
5. 是否值得进入真机验证与正式鸿蒙适配阶段；需要投入什么改造和持续维护成本？

0.2 最终结论卡（实施后填写）

项目	结果
推荐级别	部分通过；尚不足以给出 Conditional Go
使用的 Flutter_OH 版本	Flutter 3.41.10-ohos-1.0.0；Dart 3.11.5
App 基线	harmony_3.41.9 分支；使用默认 lib/main.dart（未指定 flavor 时加载 dev 配置）
模拟器基线	待记录 DevEco Studio、SDK、设备镜像/API、系统 Build
已证明的能力	OHOS 工程存在；依赖解析完成；debug HAP 可由 Flutter_OH + hvigor 构建输出
未证明的能力	模拟器运行/热重载、Dart/ArkTS 桥接、真机相机与实体扫码、相册/文件、权限、定位、推送、性能、签名发布、真实 F6 页面
下一阶段 Gate	先完成宿主 MethodChannel 探针与模拟器运行，再至少一台目标真机上的原生能力、真实 H5/F6、稳定性与发布验证

结论规则： 本轮 HAP 构建通过仅证明工具链和 Dart 编译链路可用，不能推导出 App 已可运行或原生能力已接通。没有真机时，即使模拟器中所有计划项通过，本 POC 的最高结论也只能是 Conditional Go。只有工具链、代表性业务闭环、JSBridge 和 ArkTS 原生桥接均不存在不可控阻塞时，才能建议进入真机阶段。

0.3 已获得的构建证据与未关闭项

在 App 仓库根目录执行 . .\enable-ohos.ps1，再进入 app 目录执行：

flutter build hap --debug

依赖解析及 hvigor 构建成功，输出 app/ohos/entry/build/default/outputs/default/entry-default-unsigned.hap。该产物是未签名的 debug HAP，不等同于已安装、已启动或可发布的完整验证。构建期间仍有 targetSdkVersion 未显式配置的 hvigor warning，需在后续 OHOS 工程配置中处理。

首次依赖解析曾因 Dart 3.11.5 不满足 ^3.12.0，以及 Flutter 固定 meta 1.17.0 与较新 Riverpod generator 的 analyzer 约束冲突而失败。当前 harmony 兼容组合为 flutter_riverpod 3.2.1、riverpod_annotation 4.0.2、riverpod_generator 4.0.3、pigeon 26.3.1；已对受影响包重新执行 Riverpod codegen 后构建通过。native_scan 现存 Pigeon 产物的生成版本标头仍须在后续以锁定的 Pigeon 26.3.1 重新生成或核验，这是生成物完整性检查，不代表 OHOS bridge 已完成。

1. 验证对象、范围与边界

1.1 POC 对象

• 代码基线： 已有、可运行的 Android / iOS Flutter App 源码；实施开始前记录一个确定的 Git Commit。
• 工作分支： 从该 Commit 创建 harmony 分支。POC 不直接向主干回灌鸿蒙改造。
• 运行环境： DevEco Studio 的 OpenHarmony 模拟器；设备型号、系统镜像、API 级别和 Build 均须记录。
• H5 验证对象： POC 自带的可控测试页，而不是 F6 正式页面；因此验证的是 App 容器与桥接契约，不代表真实 F6 已完成联调。
• 后端数据： 如需调用真实接口，只能使用开发/测试环境及测试账号，不使用生产数据。

1.2 本轮范围

1. Flutter_OH 工具链、OHOS 工程、依赖解析、编译、安装、启动、调试和热重载可行性。
2. 一个代表性业务闭环：登录/已有会话 → 首页 → 一个真实业务页面，覆盖路由、状态管理、网络、加载态、空态和错误态。
3. 现有 WebView 容器及 JSBridge：可控 H5 页完成握手、H5→App 调用、App→H5 回调、成功/失败回包、未知方法和来源校验。
4. OHOS 原生宿主桥接路径：Dart 公共 API → native_* 内部 MethodChannel → app/ohos/entry ArkTS 实现 → 成功结果与标准错误回传。
5. 当前依赖与原生能力的 OHOS 兼容矩阵、实际代码改动分类和维护成本评估。
6. Android / iOS 共享代码的回归检查，确认鸿蒙分支没有破坏既有行为。

1.3 明确不在本轮结论内

能力	本轮处理方式	原因与后续 Gate
相机实拍、二维码/条码实体扫码、车牌/VIN 识别	仅验证编译、注册、调用及错误语义	模拟器不能替代真实镜头、权限和硬件 SDK；必须真机验证
相册、文件选择、真实文件上传、运行时权限	可记录模拟器观察，但不关闭验收	与真实设备系统服务、路径和权限行为有关
定位、蓝牙、推送、后台任务、埋点/崩溃 SDK	登记兼容性与实现路径	未纳入代表性最小闭环，留待真机专项验证
真实 F6 页面、票据、账号与业务联调	仅验证共同的 JSBridge 契约	依赖外部环境、账号和排期
性能、功耗、包体、机型兼容、商店上架	不评估	需要真机、正式签名和稳定性测试
全部业务模块	不评估	本 POC 只证明一条代表性链路，不能外推为全量适配完成

2. Flutter_OH 技术现状与调研方法

2.1 术语与上游边界

本文中的 Flutter_OH 指 OpenHarmony-SIG 维护的 Flutter OpenHarmony 适配分支及其工具链，不是 Google Flutter 主线内置的平台。安装前不得把“flutter_harmony”作为既定的工具或包名；应以实际选定的上游仓库、Tag/Commit、安装说明和命令输出为准。

当前调研以 OpenHarmony-SIG 的 flutter_flutter 仓库和其环境搭建指南作为一手资料。官方资料说明该仓库是 OpenHarmony Flutter SDK 的来源，并以 dev / master 等分支说明安装与开发环境；POC 必须锁定实际使用的 Tag 或 Commit，避免“使用最新版”这种不可复现的描述。Flutter_OH 上游 README · OpenHarmony Flutter 环境搭建指南

2.2 调研记录表（实施前先补齐）

维度	需要记录的事实	证据来源
上游治理	维护组织、仓库、许可证、分支策略、发布机制	上游仓库 README、LICENSE、Release、治理页面
版本匹配	App 当前 Flutter/Dart 与 Flutter_OH Tag/Commit 的对应关系和版本滞后	flutter --version、Git Tag/Commit、构建日志
社区健康度	最近 12 个月提交、Release、Issue/PR 活跃度及关键问题响应	上游仓库公开记录，注明采集日期
构建链路	Windows、DevEco Studio、OpenHarmony SDK、ohpm/hvigor、Node/Java 的实际要求	官方环境文档 + 本地命令输出
插件生态	项目实际依赖的 OHOS 状态与替代方案	插件官方仓库/包说明 + 本 POC 构建结果
可维护性	项目团队需自维护的 ArkTS、fork、版本升级和 CI 工作	POC 改动清单、Issue、风险登记

2.3 首个硬门禁：SDK 匹配

Android/iOS 当前锁定 Flutter 3.44.9；Flutter_OH 上游文档计划在 2026 年 9 月提供对应的 3.44.x / Dart 3.12.x 版本。该计划是后续 SDK 收敛的候选窗口，不替代实际 Tag/Commit、依赖和构建验证。POC 首先执行以下判断：

1. 选定 Flutter_OH 的可复现 Tag/Commit；不直接使用会变化的“最新 dev”。
2. 记录该 SDK 的 Flutter/Dart 版本，并与 Android/iOS 基线、pubspec.lock、插件约束逐项比较。
3. 用未改业务的 App 基线完成依赖解析和 OHOS 编译。
4. 若版本无法兼容，立即记录为阻塞：是需要升级/降级 Flutter、替换依赖，还是当前无可行版本；不得通过私自改动业务代码或跳过插件来宣称“原代码可复用”。

只有该门禁通过，才能进入业务和原生能力验证。

3. 基线、分支与环境冻结

3.1 分支策略

1. 在实际 App 仓库确认 Android/iOS 基线已构建和测试通过。
2. 记录基线 Commit、当前 Flutter/Dart/FVM 版本、pubspec.lock、Android/iOS 构建结果。
3. 由该 Commit 创建 harmony 分支；所有 OHOS 改动仅在该分支提交。
4. 不改变既有 Android/iOS 对外业务 API；平台差异收敛在构建配置、native_* 内部 transport 与 App 宿主 ohos/entry ArkTS 层。Feature、H5 和 Dart entrypoint 不直接调用 OHOS channel。
5. 每次关键里程碑提交均在本文附录登记 Commit、变更摘要、构建命令和结果。

3.2 环境锁定表（实施时填写）

项目	固定值	证据
Windows 版本 / 架构	待填写	winver / 系统信息
DevEco Studio	待填写	About 截图 / 版本命令
OpenHarmony SDK / API	待填写	SDK Manager 截图 / 配置
模拟器镜像与 Build	待填写	Device Manager / 系统设置截图
Node / Java / ohpm / hvigor	待填写	版本命令输出
Flutter_OH 来源、Tag、Commit	待填写	git remote -v、git rev-parse HEAD
Flutter / Dart 版本	待填写	flutter --version
App 基线 Commit	待填写	git rev-parse HEAD
Pub 缓存、镜像与代理	待填写	环境变量与配置，脱敏后归档

3.3 证据归档规则

• 每条验证结论至少附一个可复现命令日志和一个可观察证据（截图、录屏、构建产物或测试输出）。
• 截图、录屏和日志放入 tech-selection/assets/flutter-oh-poc/<YYYYMMDD>/；正文只引用相对路径和简短说明。
• 日志中出现 Token、Cookie、账号、内网地址、签名或密钥时，归档前必须脱敏。
• 失败项保留完整报错、最小复现命令、尝试过的版本/方案和最终阻塞判断，不能只写“暂不支持”。

4. 可执行教程：从现有 App 跑到鸿蒙模拟器

本章是 POC 的操作手册。请严格按顺序执行：每一步先记录实际命令和输出，再进入下一步。遇到失败时，不要通过删除依赖、注释业务代码或改用空白 Demo 来“跑通”；先把失败作为兼容矩阵的一条证据记录下来。

4.1 我们如何分工

阶段	我可协助完成的工作	需要你在本机 / GUI 中完成的工作	你需要回传的最小信息
基线确认	检查 Git、Flutter、依赖、现有测试与改造差异	打开实际 App 源码仓库	仓库路径、基线分支/Commit、flutter --version
Flutter_OH 安装	给出命令、检查版本和环境变量、解释报错	下载/克隆 SDK，配置本机工具	Flutter_OH 路径、Tag/Commit、版本输出
DevEco 与模拟器	根据截图判断配置与设备识别问题	安装 DevEco Studio/SDK，在 Device Manager 创建并启动模拟器	DevEco 版本、模拟器截图、系统/API Build
项目迁移与构建	分析依赖、代码和构建报错，给出最小修复建议	在真实 App 仓库执行命令、打开/运行 OHOS 工程	完整命令、报错文本、相关文件片段
运行效果验证	制定逐页检查单，核查截图/录屏和日志	在模拟器中登录、点击页面、观察 Flutter UI 与调试输出	截图/录屏、用例编号、实际/预期差异
原生能力与 H5	审查 ArkTS/Flutter 接口、JSBridge 协议和错误语义	触发可在模拟器中操作的调用，保存日志	请求/响应、插件日志、模拟器表现

4.2 开始前：确认 App 基线没有问题

目标： 证明后续问题来自 OHOS 接入，而不是原 Android/iOS 基线本身。

在实际 Flutter App 仓库根目录执行。以下命令中的 <...> 是你需要替换的占位符；输出不要包含账号、Token 或内网地址。

git status --short
git branch --show-current
git rev-parse HEAD
flutter --version
flutter doctor -v
flutter pub get

然后执行该仓库既有的静态检查和测试命令；若项目使用 Melos、FVM 或 CI 脚本，优先用项目已有脚本，不能自行换一套命令。记录：

• 当前分支和 Commit；必须是 Android/iOS 已可运行、可复现的基线。
• Flutter、Dart、FVM（如有）和依赖锁文件版本。
• 已通过的检查及失败项；失败项先在原平台澄清，不带入鸿蒙 POC。

检查点 G-00： 只有基线可复现时，才创建 harmony 分支。

git switch -c harmony
git status --short

预期结果是当前分支为 harmony，工作区没有与本 POC 无关的未提交改动。将基线 Commit 和创建分支后的 Commit 写入“3.2 环境锁定表”。

4.3 安装 Flutter_OH：先锁版本，再配置 PATH

目标： 不使用模糊的“安装鸿蒙 Flutter”，而是得到一个能追溯到上游 Commit 的 SDK。

1. 阅读上游 README 和环境搭建指南，选择一个候选 Tag 或 Commit。不要直接把当前 Android/iOS Flutter 版本假定为已有对应 OHOS 版本。
2. 在 Windows 上将 Flutter_OH、实际 App 工程及其本地插件放在同一个磁盘分区；这是上游 Windows 环境说明中的约束。建议使用空间充足的开发盘，例如 D:\dev\。
3. 克隆上游后固定 Commit，再把该 SDK 的 bin 临时加入当前 PowerShell 会话的 PATH。示例：

$flutterOhRoot = 'D:\dev\flutter_flutter'
git clone https://gitee.com/openharmony-sig/flutter_flutter.git $flutterOhRoot
git -C $flutterOhRoot fetch --tags
git -C $flutterOhRoot checkout <已确认的Tag或Commit>
git -C $flutterOhRoot rev-parse HEAD

$env:Path = "$flutterOhRoot\bin;$env:Path"
flutter --version
flutter doctor -v

4. 把 git remote -v、最终 Commit、flutter --version 和 flutter doctor -v 的输出归档到附录 A 的 E-01。只有这些信息完整时，才可以称为“某版本 Flutter_OH 的验证结果”。

检查点 G-01： flutter --version 必须来自 Flutter_OH 路径，且其 Flutter/Dart 版本与 App 基线及 pubspec.lock 的约束不存在立即冲突。若 pub get 已经失败，停止向后执行，先在 4.7 的故障表登记版本/依赖问题。

4.4 DevEco Studio 与模拟器：由你操作的 GUI 步骤

1. 安装与选定 OpenHarmony SDK 匹配的 DevEco Studio，并通过 SDK Manager 安装目标 API、模拟器镜像、ohpm/hvigor 所需组件。
2. 打开 DevEco Studio 的 Device Manager，创建一个 Phone 模拟器；启动后进入系统设置，截图记录设备型号、OpenHarmony/HarmonyOS 版本、API 级别和 Build。
3. 保持模拟器运行，在 PowerShell 中执行：

flutter devices

4. 从输出中找到 OHOS 模拟器对应的 <device-id>。不要手工猜测设备 ID；将完整输出保存到 E-01。

检查点 G-02： flutter devices 能列出正在运行的 OHOS 模拟器。若只显示 Windows/Chrome/Android 等设备，先不要执行 flutter run；检查模拟器是否真的启动、DevEco SDK/环境变量是否与 Flutter_OH 匹配，再保存 flutter doctor -v 和 flutter devices 输出供排查。

4.5 使用既有 OHOS 工程首次运行

app/ohos 已在本轮生成并完成 HAP 构建，不得重复执行 flutter create --platforms ohos .。项目使用唯一 Dart 入口 lib/main.dart；未指定 flavor 的 OHOS 默认加载 dev 配置。

只有在一个新的 harmony 工作树中确认 app/ohos 缺失、并在运行前后人工审查 Git diff 时，才允许在 app 目录执行一次 flutter create --platforms ohos .。当前工作树的后续运行与构建从仓库根目录执行：

. .\enable-ohos.ps1
cd app
flutter pub get
flutter devices
flutter run --debug -d <device-id>

上游 README 公开了 flutter create --platforms ohos <projectName>、flutter devices、flutter run --debug -d <device-id> 和 flutter build hap --release 作为 OHOS 工程的创建、设备发现、调试运行和正式构建入口。本 POC 仅在 OHOS 平台目录缺失时使用一次 --platforms ohos 生成；任何生成操作前后都要看 Git diff，防止工具意外改写 Android/iOS 配置。上游 Flutter_OH README

首次运行时你的操作是：

1. 在模拟器中观察 App 是否安装、是否出现启动页、是否白屏/闪退。
2. 在终端保留完整输出；运行中的 Flutter 工具可用 r 触发热重载、R 触发热重启、q 退出。
3. 截取首屏和终端成功日志；若失败，复制第一段真正的 Error / Exception 及其前后上下文，不要只发最后一行。

首次可运行后执行一次构建验证（若只需复现本轮已通过的编译证据，也可直接执行本命令）：

flutter build hap --debug
git status --short
git diff --stat

检查点 G-03： HAP 调试构建已通过；调试运行和热重载仍待执行。只有三者均成功、OHOS 生成物及必要配置可在 harmony 分支中解释，且 Android/iOS 文件没有出现非预期改动时，才关闭本检查点。

4.6 观察 Flutter 业务代码的实际运行效果

工具链启动成功后，不要马上开始大面积改插件。先用现有业务代码跑完以下最小闭环，借此区分“Flutter 共享代码可以直接复用”与“某个插件阻塞启动”。

1. 在模拟器进入登录页，或按项目已有方式恢复测试登录态。
2. 完成登录后确认首页可显示，依次检查文本、图片、列表、底部导航、路由进入/返回和加载态。
3. 打开一项依赖接口数据的真实业务页面，记录成功、空数据、网络异常或服务端异常时的表现。
4. 对一个纯 Dart/Flutter 的可见文案做极小修改，执行 r 热重载，截图记录修改前后；这证明 Flutter 调试循环正常，不等于全量业务已适配。
5. 对每个异常记录：页面、操作、预期、实际、终端日志、截图路径、初步归属（Dart/UI、插件、OHOS 工程、服务端）。

建议回传给我的单条问题格式如下，我可以据此继续分析并给出下一步代码改动：

用例编号：B-03
当前 Commit：<harmony 分支 commit>
操作：登录后点击“库存”进入列表
预期：显示列表；网络失败时显示已有重试页
实际：页面白屏 / 正常 / 报错文案
终端完整异常：<从第一行 Error 到堆栈结束>
截图或录屏：<相对路径>
是否可复现：每次 / 偶发；复现步骤

4.7 逐个处理依赖，而不是一次性删掉所有插件

首次 flutter pub get、flutter run 或 flutter build hap 很可能暴露不支持 OHOS 的依赖。处理顺序固定如下：

1. 从第一个阻塞错误开始，记录包名、版本、错误、调用方和业务影响。
2. 查该依赖的官方仓库/包说明及 OpenHarmony 适配实现；把结论写入 5.2 的兼容矩阵。
3. 判定为“直接复用 / 小幅适配 / OHOS 专项实现 / 替换依赖 / 当前不可行”之一。
4. 对不影响启动的非核心依赖，可临时显式返回 Unsupported 以继续验证业务主链路；该临时降级必须在风险台账中登记，不能删除调用或伪造成功。
5. 每完成一个依赖的处理，重新执行 flutter pub get、flutter build hap --debug 和最小业务闭环，确保没有引入回归。

建议优先级如下：

优先级	依赖/能力类别	原因
P0	Flutter SDK、状态管理、路由、网络、认证、基础存储	决定 App 能否启动和承载真实业务
P0	WebView / JSBridge	该项目的核心业务链路会嵌入 F6 页面
P1	扫码、相机、文件、权限的原生注册与桥接	验证可维护的 ArkTS 宿主接入路径；真实硬件留待真机
P2	定位、蓝牙、推送、埋点、崩溃上报、弱网	本轮记录实现路径与风险，不阻塞代表性闭环

4.8 验证 WebView 与可控 H5 测试页

本轮不等待 F6 环境。先在 App 内加载一个由 POC 管理的测试页，验证容器与 JSBridge 的安全协议。测试页只用于调试，不能替代真实业务 H5。

1. 沿用 core_webview 中已有的目标白名单、来源校验、请求 ID 和回包格式；不要新建一套“POC 专用协议”。
2. 测试页依次发起 ping / 获取 App 信息、一个纯 Dart 回包、一个需进入原生适配层的调用，以及一个故意错误的调用。
3. 每个请求在页面上显示 { id, method, params }，并显示来自 App 的成功回包或错误码；App 日志同时记录相同 id，以便定位跨端问题。
4. 验证未知方法、类型错误参数和非白名单来源被拒绝，且不会触发原生能力。
5. 再由 App 向 H5 回发一个事件或结果，确认 H5 可关联到原请求。

当你在模拟器中执行时，请对每条 W-01 至 W-06 用例保存一张“请求 + 回包”的截图，并附同一 id 的 Flutter 日志。若 WebView 本身无法编译或加载，这本身是 P0 兼容性结论，不要绕过它改为浏览器打开测试页。

4.9 验证 Dart → ArkTS 原生宿主桥接

模拟器不能证明相机和扫码可用，但可以验证“项目有能力把原生功能接进来”。按以下最小路径实现和验证：

1. 找到项目当前原生能力的公共 Dart API；架构上始终由 native_* 对外暴露，Feature 和 H5 不直接依赖通道实现。
2. 不给 native_* 添加 OHOS plugin 声明，也不创建 package 内 ohos/ 目录。在 app/ohos/entry/src/main/ets/ 增加宿主桥接注册和 ArkTS 实现；EntryAbility.ets 只保留生命周期、Flutter engine 与 bridge 注册。
3. 先实现不使用硬件的 getPlatformInfo 或 echo 探针：native_* 内部 MethodChannel 传入固定参数，ArkTS 返回平台信息/同一参数，Dart 映射为类型化结果。
4. 人为触发一个可预期失败，例如未知操作或硬件不可用；验证 Dart 最终收到标准错误，而不是裸 PlatformException、空值或无限等待。
5. 再接通现有 native_scan / native_media 的入口，只验证 facade 能进入 OHOS 分支、宿主 bridge 可编译，并正确报告“待真机”的硬件不可用状态。

对每一个 Dart ↔ ArkTS 方法，在本文附录或实际宿主实现目录维护一行契约：channel 名、方法名、参数、返回值、错误码、Dart 调用点、ArkTS 实现文件。Pigeon 不生成 ArkTS，且不得人工复刻其 BasicMessageChannel、自定义 codec 和生成 envelope；这张契约表是手写 MethodChannel 防止接口漂移的最低要求。

4.10 常见失败的处理顺序

现象	优先检查	不应采取的做法
flutter 仍指向官方 SDK	Get-Command flutter、PATH 优先级、flutter --version	混用两个 SDK 后继续构建
flutter devices 没有 OHOS 模拟器	DevEco 中设备是否启动、SDK/环境变量、flutter doctor -v	手工伪造 device-id
flutter create 或构建报版本/引擎错误	Flutter_OH Commit、Flutter/Dart 版本、同盘约束、完整错误日志	强行升级/降级依赖而不记录
某个插件没有 OHOS 实现	兼容矩阵、插件说明、调用影响范围；区分第三方 plugin 与 App 宿主 bridge	直接删除依赖或把业务调用注释掉
启动白屏/闪退	第一个异常、EntryAbility bridge 注册、OHOS 工程配置、最小业务入口	只截最后一行错误
WebView 加载失败	WebView 依赖 OHOS 支持、白名单、控制台/Flutter 日志	改用外部浏览器来宣称 H5 通过
相机/扫码不可用	是否为模拟器硬件限制、插件是否已注册、错误码	以 mock 成功结果替代真机测试

4.11 每日回填与协作节奏

每完成一个 Gate，在“附录 A. POC 证据索引”新增一行，并在对应验证表将状态从“待填写”改为“通过 / 部分通过 / 失败 / 待真机”。建议以以下最小包回传，我可以据此继续带着你推进：

1. 当前 harmony 分支 Commit 与本次执行的命令。
2. 原始终端输出或脱敏后的完整日志文件。
3. 模拟器截图/录屏，以及对应的用例编号。
4. git diff --stat；若改了配置或插件，再附相关文件的 diff。
5. 你对“预期 / 实际”的一句话说明。

我会据此判断是环境问题、Flutter_OH 版本问题、第三方插件问题、共享 Dart 代码问题还是必须留待真机的问题，并给出下一条最小可执行操作，而不是让你一次性排查整套鸿蒙工具链。

5. 实施步骤与记录模板

5.1 工具链与 OHOS 工程

步骤	实施动作	通过标准	实际结果 / 证据
T-01	按官方资料安装 Flutter_OH 与依赖工具	flutter --version 显示锁定版本；环境变量配置可复现	待填写
T-02	配置 DevEco Studio、OpenHarmony SDK 和模拟器	模拟器可启动并被工具识别	待填写
T-03	在 harmony 分支生成/补齐 OHOS 工程	工程结构完整，配置不污染 Android/iOS	待填写
T-04	执行依赖解析和调试构建	无阻塞性依赖或编译错误	待填写
T-05	安装并启动 App	首屏正常显示，无启动崩溃	待填写
T-06	调试与热重载	可附加调试器；关键 Dart 修改生效	待填写

5.2 代码复用与依赖兼容矩阵

对每个实际依赖和代码层做如下分类，禁止使用笼统的“基本兼容”。

分类	定义	典型处理
直接复用	不改源码或仅改构建声明即可运行	纯 Dart 模型、业务规则、通用 Flutter UI
小幅适配	局部条件分支、配置或 API 替换后运行	平台判断、路径、主题或插件初始化
OHOS 专项实现	需要新增 ArkTS 宿主实现或已验证的第三方 OHOS 实现	App ohos/entry bridge、特定系统能力
替换依赖	原依赖不支持 OHOS，需使用功能等价方案	WebView、存储、设备/媒体 SDK 等
当前不可行	没有可控实现路径或风险不可接受	记录最小复现、影响范围和 No-Go 条件

实施后至少填充以下矩阵：

层 / 能力	当前实现或依赖	OHOS 分类	改造内容	证据	风险与责任方
Dart 业务模型与 Use Case	待填写	待填写	待填写	待填写	待填写
Flutter UI、主题、路由、Riverpod	待填写	待填写	待填写	待填写	待填写
网络、认证、错误处理、存储	待填写	待填写	待填写	待填写	待填写
WebView / JSBridge	core_webview	待填写	待填写	待填写	待填写
扫码、相机、媒体、文件	native_* 或实际项目实现	待填写	待填写	待填写	真机 Gate
权限、定位、推送、蓝牙	实际项目实现	待填写	待填写	待填写	真机 Gate
日志、埋点、崩溃上报	实际项目实现	待填写	待填写	待填写	待填写

5.3 代表性业务闭环

业务闭环选用真实 App 中已经存在的页面和状态流，而不使用新的 Demo 页面伪造成功结果。建议顺序为：

已有登录态或测试登录 → 首页 → 一项需要接口数据、路由跳转和状态管理的业务页面 → loading / data / empty / error 状态

用例	前置条件	操作与预期	状态	证据
B-01 启动与会话恢复	已配置测试环境	App 启动后按既有逻辑进入登录或首页	待填写	待填写
B-02 登录 / 测试会话	测试账号或可控会话	鉴权成功，凭据和门店上下文按预期处理	待填写	待填写
B-03 首页与路由	已登录	首页渲染，进入选定业务页并可返回	待填写	待填写
B-04 业务数据成功态	测试接口可用	数据正常加载和展示	待填写	待填写
B-05 空态与错误态	可控响应或测试数据	提示、重试和错误映射符合既有约定	待填写	待填写

5.4 WebView 与 JSBridge

当前架构将 Embedded H5 及 JSBridge 收敛在 core_webview，并由 native_* 暴露原生能力；POC 必须沿用该边界，不能为了临时跑通而让 H5 直接调用 ArkTS。现有设计请参见 Embedded H5 容器与 JSBridge 和 原生能力集成方式。

POC 自带的 H5 测试页必须可显示每次请求的 id、method、参数、响应及错误码，并覆盖：

用例	预期
W-01 页面加载与桥接就绪	白名单页面加载后可确认 App Bridge 已就绪
W-02 H5 → App 合法调用	参数通过校验，App 调用现有能力并回传与协议一致的结果
W-03 App → H5 回调	H5 正确收到事件/结果，id 可关联请求与回包
W-04 未知方法 / 非法参数	返回明确错误，不执行任何原生能力
W-05 非白名单来源	拒绝调用并记录安全日志，不泄露内部信息
W-06 原生能力不可用	返回标准化 UNSUPPORTED、PERMISSION_DENIED 或 HARDWARE_UNAVAILABLE，不静默返回空值

本节通过只能说明 App 容器和桥接协议 可行。F6 真页的页面加载、登录态、文件上传、票据和业务流程仍必须在后续联调中单独验收。

5.5 OHOS 原生宿主桥接与 ArkTS 验证

目标是证明项目有可维护的原生接入路径，而不是在没有真机时伪造扫码成功。

1. 在既有 native_* 的 Dart facade 内增加 OHOS transport，并在 App 宿主 ohos/entry 实现 ArkTS bridge；若基线尚未包含目标能力，可新增仅限 POC 的 native_capability_probe，但不能把它伪装成正式扫码实现。
2. 以一个不依赖相机硬件的探针方法验证完整通道：Dart facade 发起调用、EntryAbility 注册宿主 bridge、ArkTS 接收参数、返回类型化结果、Dart 映射成功与失败。
3. 以现有 native_scan / native_media 对外 API 的调用路径验证 facade 分派、宿主 bridge 编译和错误语义；没有硬件时，结果必须标为“待真机”，不得以模拟值代替扫描结果。
4. 记录手写 ArkTS MethodChannel 的 channel 名、方法名、参数/返回值、错误码和接口漂移防护方案；不要求、也不尝试为 Pigeon 生成或手写 ArkTS wire protocol。
5. 不向业务 Feature 暴露 MethodChannel、ArkTS 或平台判断；业务和 H5 只能依赖 native_* 公共 Dart API。

用例	验收标准	模拟器结论
N-01 宿主 bridge 编译与注册	OHOS 工程可编译；启动日志证明 EntryAbility 已注册 bridge	可关闭
N-02 Dart → ArkTS → Dart	参数、返回值及异常可在两端对应	可关闭
N-03 不支持/硬件不可用错误	返回明确、可追踪的标准错误	可关闭
N-04 相机与实体扫码	真实打开相机、完成识别、处理拒绝权限	必须待真机
N-05 文件/相册与权限	真实系统服务、路径、取消与拒绝场景	必须待真机

6. 验收、回归与决策

6.1 验收状态定义

状态	使用条件
通过	有完整命令、日志和可观察证据，达到预期结果
部分通过	主链路可行，但存在明确限制、人工步骤或未关闭风险
失败	当前版本或实现无法达到验收标准，附最小复现和阻塞原因
待真机	模拟器不能代表真实设备；不记为失败，也不记为通过

6.2 Android / iOS 回归

• harmony 分支的共享 Dart 改动必须继续通过现有静态检查、单元测试、Widget 测试及既有集成测试。
• 若 App 当前已有 Android/iOS CI，记录实施前和实施后的流水线链接或关键输出；若尚无 CI，至少记录本地执行的等价命令与结果。
• 新增 OHOS 条件分支必须覆盖 Android、iOS、OHOS 和未知平台的行为，尤其是不支持能力的显式异常路径。

6.3 最终判定

判定	条件	后续动作
Conditional Go	SDK 匹配、构建运行、代表性业务、JSBridge、Dart/ArkTS 桥接均通过或有可控适配；硬件能力保留真机 Gate	进入真机专项验证和正式适配估算
No-Go	当前基线没有兼容 SDK，或核心业务/桥接/原生插件有不可接受阻塞且无可控替代	停止扩面，给出版本调整或替代技术路线建议

不得使用“模拟器没问题，所以鸿蒙没问题”作为结论。任何 Conditional Go 必须同时给出下列真机关闭条件：相机、实体扫码、运行时权限、文件/相册、WebView 差异、真实 F6、签名安装、性能稳定性和目标机型验证。

7. 成本与风险登记（实施后填写）

7.1 成本口径

成本不只统计首轮代码行数，按以下维度记录：

• 一次性接入成本： OHOS 工程、构建环境、依赖替换、ArkTS 插件、测试页和 CI。
• 业务适配成本： 共享代码调整、条件分支、UI/渲染差异、接口与存储适配。
• 原生能力成本： 每个 native_* 的 OHOS 实现、权限、SDK 集成、真实设备测试。
• 长期维护成本： Flutter_OH 跟随 Flutter 主线、插件 fork、ArkTS 接口漂移、社区 Issue 跟进、CI 和发布链路。

代码复用率只有在统计了确定基线和实际差异后才填写；必须同时给出统计范围，不能用一个无范围的百分比代替兼容矩阵。

7.2 风险台账

编号	风险	当前证据	影响	缓解措施	关闭条件	状态
R-OH-01	Flutter_OH 与当前 Flutter/Dart 基线版本不匹配	待验证	高	SDK 匹配作为首个硬门禁	基线编译、运行、依赖解析通过	待验证
R-OH-02	社区分支发布滞后或关键问题依赖外部修复	待调研	高	锁定 Commit、跟踪上游、评估 fork 能力	有版本升级与问题响应策略	待验证
R-OH-03	Android/iOS plugin 或三方依赖不具备 OHOS 实现	待矩阵验证	高	逐项分类、优先核心插件、明确替代方案	核心原生能力真机通过	待验证
R-OH-04	ArkTS 手写 MethodChannel 产生接口漂移	已决定不复刻 Pigeon wire protocol	中	固定 channel 契约、契约测试、native_* 公共 API 封装	Dart/ArkTS 契约自动/人工校验通过	开放
R-OH-05	模拟器结论与真机不一致	已知限制	高	所有硬件项标记待真机	目标真机专项验收完成	开放
R-OH-06	F6 WebView 在 OHOS 的内核与行为差异	本轮仅验证可控页	高	后续真实 F6 联调	F6 核心流程和 JSBridge 通过	开放

附录 A. POC 证据索引（实施后填写）

编号	验证项	命令/日志	截图/录屏/产物	代码 Commit	状态
E-01	SDK 与环境	待填写	待填写	待填写	待填写
E-02	OHOS 构建与安装	待填写	待填写	待填写	待填写
E-03	业务闭环	待填写	待填写	待填写	待填写
E-04	WebView / JSBridge	待填写	待填写	待填写	待填写
E-05	Dart / ArkTS 原生桥接	待填写	待填写	待填写	待填写
E-06	Android / iOS 回归	待填写	待填写	待填写	待填写

附录 B. 真机验收 Checklist（下一阶段）

• 目标 HarmonyOS / OpenHarmony 真机的签名安装、冷启动、升级与卸载重装。
• 相机权限：首次授权、拒绝、永久拒绝后的引导、从设置页恢复。
• 二维码/条码扫描、低光、连续扫码、取消、超时与异常恢复。
• 车牌/VIN 采集链路及网络异常时的手工降级入口。
• 相册、拍照、文件选择、取消、无权限、文件路径、压缩与上传进度。
• 定位、蓝牙、通知/推送、后台恢复及弱网场景。
• 真实 F6 登录、票据、双向 JSBridge、上传与返回栈。
• 多台目标机型上的 UI、WebView、性能、功耗、崩溃和日志脱敏。
• 发布签名、包体、合规声明及目标分发渠道的安装验证。