oneapp_docs/App_Harmony_Flutter_Developer/harmony_development.md

OneApp 鸿蒙（HarmonyOS）工作步骤文档

Step 0：前置约束与目标确认（必做）

• 目标
  • 在不破坏 Android/iOS 现有架构的前提下新增 HarmonyOS 支持
  • 首版功能可裁剪、可降级
• 约束
  • 不重写 Flutter 业务代码
  • 业务模块不得直接依赖平台插件
  • 鸿蒙首版不要求功能全量对齐
• 产出
  • 《鸿蒙首版功能白名单》
  • 《不支持/延后支持模块清单》

Step 1：插件与平台能力盘点（P0）

• 1.1 插件全量清点
  • 对现有 Flutter 插件形成“插件→使用模块→平台支持矩阵”
  • 核心关注：地图/定位、推送、支付、存储、设备信息、媒体、车控
  • 产出：《插件→模块→平台支持矩阵表》
• 1.2 插件分级（强制）
  • L0：纯 Dart（直接复用）
  • L1：轻平台（需补鸿蒙实现）
  • L2：重平台（能力抽象 + 原生实现）
  • L3：强绑定（首版可能不支持）
  • 产出：《插件分级治理表》

Step 2：平台能力抽象（架构改造核心，P0）

• 新增 Platform Capability Layer（统一能力抽象包）
  • 目录建议：
    • packages/platform_capability/{geo,push,payment,car_control,media,device,storage}
  • 定义跨端接口（示例）
    • GeoCapability.getLocation(), PushCapability.subscribe(), PaymentCapability.pay()
  • 强制规则
    • 业务模块不依赖任何平台插件
    • CLR 不直接引用 Android/iOS/HarmonyOS SDK
    • 所有平台能力通过 Capability 接口访问
    • Capability Interface 禁止暴露 Platform 类型（Context/Ability/Activity）
  • 产出：Capability 接口定义、依赖调整方案

Step 2A：模块化适配约束（Harmony 优先）

• 基础设施层（basic_*）
  • 原则：尽量纯 Dart 实现，避免依赖任何原生平台能力
  • 目的：降低平台适配成本，保障 Harmony 接入可持续
• 工具与组件层（kit_/ui_）
  • 原则：不直接依赖平台插件；如需平台能力，必须经 Capability
  • 目的：保持 UI/工具层跨端一致性
• 服务连接层（clr_*）
  • 原则：仅通过 Capability 访问平台能力，不直接引用 Android/iOS/Harmony SDK
  • 目的：统一平台差异收敛点，避免平台污染
• 业务模块层（app_*）
  • 原则：只依赖 basic_/kit_/ui_/clr_，禁止互相强依赖
  • 目的：保证模块边界清晰、可裁剪、可灰度

验收要点

• basic_* 不含原生依赖
• kit_/ui_ 不出现 Platform 类型（Context/Ability/Activity）
• clr_* 仅调用 Capability 接口
• app_* 无跨层直接依赖

Step 3：CLR 模块改造（P0–P1）

• 去插件化
  • 将 clr_* 模块中的“直接插件/Native SDK 调用”替换为 Capability 调用
  • 适配模块：clr_geo、clr_account、clr_message、clr_charging、clr_touchgo、clr_wallbox、clr_carwatcher
  • Before：CLR → Plugin → Native
  • After：CLR → Capability → Platform Impl
  • 产出：CLR 重构完成，Android/iOS Capability 实现保持不变

Step 4：HarmonyOS 宿主工程与 Flutter 引擎接入（P0）

• 4.1 宿主工程结构（建议）
  • Flutter 业务代码保持唯一真源
  • HarmonyOS 宿主与 Android/iOS 宿主同级或并列目录即可
  • 示例结构
    • oneapp/
      • flutter/
        • lib/
        • packages/
        • pubspec.yaml
      • host_android/
      • host_ios/
      • host_harmony/
  • 产出：《鸿蒙宿主工程结构与路径规范》
• 4.2 HarmonyOS 启动流程与参数策略
  • Harmony 宿主决定“给 Flutter 什么参数”
  • 启动流程
    • Harmony Ability
    • 初始化 Flutter Engine
    • 注入启动参数（appMode/featureFlags）
    • runApp(main.dart)
  • 最小启动策略（首版）
    • 只做三件事：启动 Engine、注册最小插件集合、指定初始路由
    • 启动参数语义
      • appMode：应用形态（如 harmonyLite）
      • featureFlags：模块开关（如 map/pay/carControl）
    • Harmony 宿主在 Engine 初始化阶段向 Flutter 注入启动参数
    • Flutter 启动后通过统一入口获取启动参数
    • Flutter 层保持完整 App，只是能力不可用或返回 not supported
    • iOS/Android 不改动，默认无 args
  • 产出：《Harmony 启动参数规范》《最小插件集合清单》

Step 5：HarmonyOS 原生能力实现（P1）

• Capability 的鸿蒙实现
  • Geo → Map Kit
  • Push → Push Kit
  • Payment → IAP
  • Storage → Preferences
  • Device/Media/CarControl → 系统/厂商 API
  • 通过 MethodChannel 暴露给 Flutter
  • 产出：鸿蒙 Capability 实现代码（Flutter 侧透明）

Step 6：模块级功能适配与裁剪（P1–P2）

• 首版必保模块（建议）
  • oneapp_main、app_home、oneapp_account
  • clr_account / clr_geo / clr_message
  • app_car / app_charging（基础能力）
• 可延后模块
  • app_avatar、app_rpa、app_vur、3D/AI/音视频增强模块
• 策略
  • 模块级 feature flag
  • UI 隐藏 / 功能降级
  • 产出：鸿蒙首版功能闭环

Step 7：分阶段落地顺序（强执行）

• 阶段 1（POC）
  • 新建 host_harmony
  • Flutter 首页跑通
  • 只接入：网络、存储、账号
  • 产出：鸿蒙最小可运行包
• 阶段 2（核心可用）
  • 跑通：app_home、app_discover、clr_account、clr_message
  • UI 完整，部分按钮 disabled 或降级
  • 产出：核心场景闭环
• 阶段 3（逐模块放开）
  • 每新增模块：宿主补插件、Flutter 放 feature flag、打通 clr → app
  • 启动参数示例
    • appMode: "harmonyLite"
    • featureFlags: { map: false, pay: false, carControl: false }
  • 产出：模块级逐步放量清单

Step 8：多宿主构建与 CI 约束（P1）

• 约束
  • flutter/ 目录为唯一真源
  • host_harmony 仅负责 Engine 初始化与插件注册
  • Flutter 代码不得 import host_harmony 相关实现
  • Capability 必须有 Android/iOS 默认实现
• 产出
  • Flutter lint / 构建校验规则

Step 9：测试与稳定性验证（P2）

• 测试重点
  • Flutter 启动稳定性
  • MethodChannel 调用一致性
  • 权限 / 生命周期
  • 弱网 / 异常兜底
• 真机测试（必须）
  • 至少 2–3 款鸿蒙设备
  • 不以 Emulator 结论替代真机结果
  • 产出：测试报告与问题清单

Step 10：上架与合规检查（P2）

• 审核重点
  • 权限最小化
  • 无动态代码下载
  • SDK 合规（华为生态）
• 发布
  • 华为应用市场
  • 首版灰度发布
  • 产出：合规材料与发布记录

附录：可视化补充（可直接插入评审材料）

附录 A：多宿主 + Flutter 架构示意

                  ┌───────────────┐
                  │   Flutter UI  │
                  │   lib/*       │
                  └───────┬───────┘
                          │ Capability 接口
          ┌───────────────┴─────────────────┐
          │                                 │
      ┌───▼─────────┐                   ┌───▼─────────┐
      │  Android    │                   │   iOS       │
      │ Platform Impl│                  │ Platform Impl│
      └─────────────┘                   └─────────────┘
                          │
                          │
                  ┌───────▼───────────┐
                  │ HarmonyOS Platform│
                  │ Impl (ArkTS/Java) │
                  └───────────────────┘

• Flutter 层唯一真源，业务模块不依赖平台
• Capability 层统一接口访问原生能力
• HarmonyOS / Android / iOS 只提供实现

附录 B：HarmonyOS 启动流程图

┌─────────────────┐
│ Harmony Ability  │
└─────────┬───────┘
          │ 初始化 Flutter Engine
          ▼
┌─────────────────────────┐
│ 注入启动参数 initialArgs │
│ appMode / featureFlags   │
└─────────┬───────────────┘
          │ 注册最小插件集合
          ▼
┌───────────────────┐
│ runApp(main.dart) │
│ Flutter 层启动     │
└───────────────────┘

• 初版策略：只启动 Engine、注册最小插件、指定初始路由
• Flutter 层保持完整 App，可根据 featureFlags 降级模块

附录 C：Feature Flags 可视化表

模块	首版状态	功能降级 / UI 隐藏
map	false	隐藏地图按钮
pay	false	禁用支付入口
carControl	false	禁止操作车辆
oneapp_main	true	-
app_home	true	-
oneapp_account	true	-
clr_account	true	-
clr_geo	true	-

启动参数示例：

{
  "appMode": "harmonyLite",
  "featureFlags": {
      "map": false,
      "pay": false,
      "carControl": false
  }
}

附录 D：分阶段落地甘特/流程示意

阶段 1：POC (新建 host_harmony)
 ├─ Flutter 首页跑通
 ├─ 最小插件集合
 └─ 网络 / 存储 / 账号模块可用

阶段 2：核心可用
 ├─ app_home、app_discover
 ├─ clr_account / clr_message
 └─ UI 完整，部分按钮 disabled

阶段 3：逐模块放开
 ├─ 每新增模块宿主补插件
 ├─ Flutter 放 feature flag
 └─ 打通 clr → app

阶段对应产出：

• POC → 鸿蒙最小可运行包
• 核心可用 → 核心场景闭环
• 模块放开 → 模块级逐步放量清单

参考资料（官方）

• HarmonyOS 开发者官网：https://developer.harmonyos.com
• OpenHarmony 文档中心：https://docs.openharmony.cn
• DevEco Studio（IDE）：https://developer.huawei.com/consumer/cn/deveco-studio
• 华为应用市场审核规范：https://developer.huawei.com/consumer/cn/doc/app