From 45cb240c40bb3570266228cf93cf4aee61dcb1c5 Mon Sep 17 00:00:00 2001 From: "Guangfei.Zhao" Date: Wed, 2 Sep 2026 23:33:15 +0800 Subject: [PATCH] docs: update Flutter OH POC and project structure for SDK version alignment --- POC/Flutter-OH-POC.md | 2 +- flutter-app/01-project-structure.md | 2 +- flutter-app/07-native-integration.md | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/POC/Flutter-OH-POC.md b/POC/Flutter-OH-POC.md index f01bac2..119c8b1 100644 --- a/POC/Flutter-OH-POC.md +++ b/POC/Flutter-OH-POC.md @@ -102,7 +102,7 @@ flutter build hap --debug -t lib\main_dev.dart ### 2.3 首个硬门禁：SDK 匹配 -现有工程文档把 Flutter `3.44.9` 作为未来 OHOS 的兼容窗口，但这个假设不能替代实际验证。POC 首先执行以下判断： +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`、插件约束逐项比较。 diff --git a/flutter-app/01-project-structure.md b/flutter-app/01-project-structure.md index e0c88df..5f8d06c 100644 --- a/flutter-app/01-project-structure.md +++ b/flutter-app/01-project-structure.md @@ -87,7 +87,7 @@ conti-app/ **OHOS SDK 边界**：OpenHarmony 的 Flutter 分支与官方 stable 不同步。Android/iOS 仍以 FVM 锁定的 Flutter 3.44.9 为基线；`harmony` 分支已用 Flutter_OH 3.41.10-ohos-1.0.0 / Dart 3.11.5 完成 HAP 编译验证。两套 SDK 不可混用，任一侧升级都必须重新验证依赖解析、生成代码和对应平台构建（见 [07-native-integration.md](./07-native-integration.md)）。 -**未来收敛条件**：当 Flutter_OH 发布并验证可用的 Flutter **3.44.x / Dart 3.12.x** 对齐版本时，可评审将 `harmony` 与 Android/iOS 收敛到同一 SDK 基线。版本号相同不是自动放行条件；必须重新完成依赖解析、Riverpod/Pigeon 生成物核验、HAP 构建及真机原生能力验证后才能切换。 +**未来收敛条件**：Flutter_OH 上游文档计划在 **2026 年 9 月**提供 Flutter **3.44.x / Dart 3.12.x** 对齐版本；发布实际 Tag/Commit 可获取后，可评审将 `harmony` 与 Android/iOS 收敛到同一 SDK 基线。计划日期或版本号相同都不是自动放行条件；必须重新完成依赖解析、Riverpod/Pigeon 生成物核验、HAP 构建及真机原生能力验证后才能切换。 **为什么必须用 FVM 锁**：monorepo 里各人本地 Flutter 版本不一致，会导致同一份代码有人 `flutter analyze` 过、有人不过，生成代码（`build_runner` 产物）也可能不一致——这类问题排查成本远高于装一次 FVM。CI 也用 `.fvmrc` 里的版本，保证本地和流水线一致。 diff --git a/flutter-app/07-native-integration.md b/flutter-app/07-native-integration.md index 3cafe46..4653928 100644 --- a/flutter-app/07-native-integration.md +++ b/flutter-app/07-native-integration.md @@ -291,7 +291,7 @@ app/ohos/entry/src/main/ets/ **延后抽取独立 OHOS plugin。** 只有出现第二个 OHOS App 的复用需求、扫描实现和契约已稳定、Flutter_OH plugin 注册/模板已成熟并经验证，或 SDK 化收益明确超过维护成本时，才评审将 ArkTS 从 `app/ohos/entry` 抽到 `packages/native_scan/ohos`。在此之前，不添加 `ohos:` plugin 声明或额外 `ohos/` 目录。 -**SDK 收敛条件。** 当前 Android/iOS 使用 Flutter 3.44.9，OHOS 使用 Flutter_OH 3.41.10-ohos-1.0.0；当 Flutter_OH 出现经验证可用的 Flutter 3.44.x / Dart 3.12.x 对齐版本时，可评审统一基线。升级前必须以该候选 SDK 完成依赖解析、Pigeon 与 Riverpod 生成物核验、`flutter build hap --debug -t lib\\main_dev.dart` 和真机原生能力回归；不能仅因版本号相同就替换工具链。 +**SDK 收敛条件。** 当前 Android/iOS 使用 Flutter 3.44.9，OHOS 使用 Flutter_OH 3.41.10-ohos-1.0.0；Flutter_OH 上游文档计划在 **2026 年 9 月**提供 Flutter 3.44.x / Dart 3.12.x 对齐版本。实际 Tag/Commit 发布并验证可用后，可评审统一基线。升级前必须以该候选 SDK 完成依赖解析、Pigeon 与 Riverpod 生成物核验、`flutter build hap --debug -t lib\main_dev.dart` 和真机原生能力回归；不能仅因计划日期或版本号相同就替换工具链。 ## 使用规则