# 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 架构示意

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

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

### 附录 B：HarmonyOS 启动流程图

```text
┌─────────────────┐
│ 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     | -                 |

启动参数示例：

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

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

```text
阶段 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