新大洲智能车控 HarmonyOS 移植方案

📋 项目概述

本文档制定从 Android 平台移植到 HarmonyOS 平台的详细方案，保持整体架构一致，同时针对 HarmonyOS 系统特色进行优化封装。

🎯 移植目标

核心原则

架构一致性：保持与 Android 版本相同的分层架构
鸿蒙特色：充分利用 HarmonyOS 的 ArkTS、声明式 UI、分布式能力等特性
代码复用：业务逻辑层尽量复用，UI 层和平台特性层重新实现
渐进式迁移：分阶段实施，确保每个阶段可独立验证

🏗️ 架构对比分析

Android 架构

业务层（app 模块）
    ↓ 依赖
    ├── base-common（业务封装层）
    └── capability-xxx（能力层）
            ↓ 依赖
        base-core（基础设施层）
            ↑ 依赖
        base-common（业务封装层）

HarmonyOS 目标架构

业务层（entry 模块）
    ↓ 依赖
    ├── base-common（业务封装层）
    └── capability-xxx（能力层）
            ↓ 依赖
        base-core（基础设施层）
            ↑ 依赖
        base-common（业务封装层）

架构保持一致，但实现方式不同：

Android: Gradle 模块化
HarmonyOS: oh-package.json5 模块化

📦 模块结构设计

1. base-core（基础设施层）

职责：

定义接口（给 capability 模块实现）
基础实现（日志、网络、存储）
第三方库管理（统一版本）

HarmonyOS 实现要点：

base-core/
├── src/main/ets/
│   ├── core/
│   │   ├── log/
│   │   │   ├── ILog.ets                    # 日志接口（与 Android 保持一致）
│   │   │   └── impl/
│   │   │       ├── HilogLogger.ets         # 基于 @kit.PerformanceAnalysisKit/hilog
│   │   │       └── NoOpLogger.ets          # 空日志实现
│   │   ├── network/
│   │   │   └── NetworkManager.ets           # HTTP 请求管理器（基于 @kit.NetworkKit/http）
│   │   ├── storage/
│   │   │   ├── IStorage.ets                # 存储接口（与 Android 保持一致）
│   │   │   └── StorageImpl.ets              # 基于 @kit.PreferencesKit/preferences
│   │   ├── push/
│   │   │   └── IPushService.ets            # 推送服务接口
│   │   ├── share/
│   │   │   ├── IShareService.ets            # 分享服务接口
│   │   │   └── IShareCallback.ets          # 分享回调接口
│   │   └── util/
│   │       └── IUtil.ets                   # 工具类接口
│   └── index.ets                            # 模块导出入口
├── oh-package.json5
└── README.md

关键差异：

✅ 使用 @kit.PerformanceAnalysisKit/hilog 替代 Timber
✅ 使用 @kit.NetworkKit/http 替代 Retrofit/OkHttp
✅ 使用 @kit.PreferencesKit/preferences 替代 SharedPreferences
✅ 使用 ArkTS 语言替代 Kotlin

2. base-common（业务封装层）

职责：

封装 base-core 的接口，提供便捷调用
业务工具封装（配置、网络、UI、权限等）
MVVM 架构封装
完整业务功能（认证、版本更新等）

HarmonyOS 实现要点：

base-common/
├── src/main/ets/
│   ├── common/
│   │   ├── auth/
│   │   │   ├── AuthManager.ets             # 认证管理器（与 Android 逻辑一致）
│   │   │   ├── storage/
│   │   │   │   └── TokenStore.ets           # Token 存储（使用 StorageImpl）
│   │   │   ├── datasource/
│   │   │   │   ├── remote/
│   │   │   │   │   └── AuthRemoteDataSource.ets
│   │   │   │   └── local/
│   │   │   │       └── AuthLocalDataSource.ets
│   │   │   ├── repository/
│   │   │   │   └── AuthRepository.ets
│   │   │   ├── model/
│   │   │   │   ├── LoginRequest.ets
│   │   │   │   └── LoginResponse.ets
│   │   │   └── pages/
│   │   │       ├── LoginPage.ets            # 登录页（ArkUI 声明式 UI）
│   │   │       └── RegisterPage.ets         # 注册页（ArkUI 声明式 UI）
│   │   ├── network/
│   │   │   ├── NetworkHelper.ets             # 网络管理器封装
│   │   │   ├── ApiServiceFactory.ets        # API 服务工厂
│   │   │   ├── ApiBaseRemoteDataSource.ets  # 远程数据源基类
│   │   │   └── ApiBaseRepository.ets        # Repository 基类
│   │   ├── config/
│   │   │   ├── ConfigManager.ets             # 配置管理（使用 StorageImpl）
│   │   │   └── ServerConfigManager.ets       # 服务器配置管理
│   │   ├── storage/
│   │   │   └── StorageManager.ets             # 存储管理器封装
│   │   ├── ui/
│   │   │   ├── BasePage.ets                  # 页面基类（替代 BaseActivity/BaseFragment）
│   │   │   ├── MessageHelper.ets            # 消息提示（使用 @ohos.promptAction）
│   │   │   └── NavigationHelper.ets          # 路由导航（使用 router）
│   │   ├── dialog/
│   │   │   └── DialogHelper.ets              # 对话框封装（使用 @ohos.promptAction）
│   │   ├── permission/
│   │   │   └── PermissionHelper.ets          # 权限管理（使用 @kit.AbilityKit）
│   │   ├── version/
│   │   │   ├── VersionUpdateManager.ets      # 版本更新管理器
│   │   │   └── pages/
│   │   │       └── UpdateDialog.ets           # 更新对话框（ArkUI）
│   │   ├── launch/
│   │   │   ├── AppInitializer.ets           # 应用初始化管理器
│   │   │   └── LaunchPage.ets                # 启动页（ArkUI）
│   │   └── socketio/
│   │       └── SocketIOManager.ets            # SocketIO 管理器
│   └── index.ets
├── oh-package.json5
└── README.md

关键差异：

✅ 使用 ArkUI 声明式 UI 替代 ViewBinding/XML
✅ 使用 router 模块替代 ARouter
✅ 使用 @ohos.promptAction 替代 Toast/Snackbar
✅ 使用 @kit.AbilityKit 处理权限
✅ 页面基类使用 @Component 装饰器

3. capability-xxx（能力层）

职责：

实现 base-core 定义的接口
封装第三方 SDK 或系统能力

模块列表：

capability-socketio/          # Socket.IO 能力
capability-ble/               # BLE 蓝牙能力
capability-nfc/               # NFC 能力
capability-qrcode/            # 二维码能力
capability-push/              # 推送能力（极光推送）
capability-share/             # 分享能力（友盟分享 + 微信 SDK）

关键差异：

✅ 推送：继续使用极光推送（JPush 已支持 HarmonyOS）
✅ 分享：使用友盟分享 SDK（与 Android 保持一致）
✅ 微信分享：微信 SDK 回调处理（需要特殊处理，见下方说明）
✅ BLE/NFC：使用 HarmonyOS 原生 API

4. entry（业务层）

职责：

应用入口
业务页面实现
模块初始化

HarmonyOS 实现要点：

entry/
├── src/main/ets/
│   ├── entryability/
│   │   └── EntryAbility.ets                 # 应用入口 Ability
│   ├── pages/
│   │   ├── MainPage.ets                     # 主页面
│   │   └── ...
│   └── Application.ets                       # 应用初始化（替代 Application）
├── src/main/module.json5
└── oh-package.json5

🔄 关键技术映射

1. 存储系统

Android	HarmonyOS	说明
SharedPreferences	@kit.PreferencesKit/preferences	键值存储
StorageImpl	StorageImpl (基于 preferences)	统一存储实现
TokenStore	TokenStore (使用 StorageImpl)	Token 存储

实现要点：

保持接口一致（IStorage）
底层使用 HarmonyOS preferences API
业务层无需感知差异

2. 网络请求

Android	HarmonyOS	说明
Retrofit + OkHttp	@kit.NetworkKit/http	HTTP 客户端
Gson	JSON.parse/stringify	JSON 解析
Coroutines	Promise/async-await	异步处理

实现要点：

封装 http 模块，提供类似 Retrofit 的接口
统一错误处理和响应解析
保持 Repository 模式一致

3. UI 框架

Android	HarmonyOS	说明
Activity/Fragment	Page (@Component)	页面组件
ViewBinding	ArkUI 声明式	UI 构建
Material Design	HarmonyOS Design	设计规范
Toast/Snackbar	@ohos.promptAction	消息提示

实现要点：

使用 ArkUI 声明式 UI（类似 Flutter/React）
保持业务逻辑层代码复用
UI 层完全重写

4. 路由导航

Android	HarmonyOS	说明
ARouter	router	路由导航
Intent	Want	页面跳转参数

实现要点：

封装 router 模块，提供统一接口
保持路由路径和参数传递方式一致

5. 生命周期

Android	HarmonyOS	说明
Application.onCreate	EntryAbility.onCreate	应用启动
Activity 生命周期	Page 生命周期	页面生命周期
ProcessLifecycleOwner	AppLifecycleObserver	应用前后台

实现要点：

封装生命周期管理，提供统一接口
保持业务逻辑层代码复用

6. 权限管理

Android	HarmonyOS	说明
Activity.requestPermissions	@kit.AbilityKit	权限请求
PermissionHelper	PermissionHelper (重写)	权限封装

实现要点：

保持接口一致
底层使用 HarmonyOS 权限 API

📝 移植步骤

阶段一：基础设施搭建（1-2周）

目标： 建立基础架构，验证可行性

任务清单：

创建模块结构
- 创建 base-core 模块（oh-package.json5）
- 创建 base-common 模块
- 创建 capability-socketio 模块
- 配置模块依赖关系
实现基础能力
- 实现 ILog 接口（基于 hilog）
- 实现 IStorage 接口（基于 preferences）
- 实现 StorageImpl（统一存储）
- 实现 NetworkManager（基于 http）
验证基础功能
- 存储功能测试
- 网络请求测试
- 日志输出测试

阶段二：核心业务功能（2-3周）

目标： 移植核心业务逻辑

任务清单：

认证模块
- 移植 TokenStore（使用 StorageImpl）
- 移植 AuthManager
- 移植 AuthRepository
- 实现登录/注册页面（ArkUI）
- 测试登录/注册流程
网络封装
- 封装 HTTP 请求（类似 Retrofit）
- 实现 ApiServiceFactory
- 实现 ApiBaseRepository
- 统一错误处理
配置管理
- 移植 ConfigManager
- 移植 ServerConfigManager
- 使用 StorageImpl 存储配置

阶段三：UI 和工具封装（2-3周）

目标： 完善 UI 层和工具类

任务清单：

UI 基础类
- 实现 BasePage（页面基类）
- 实现 MessageHelper（消息提示）
- 实现 DialogHelper（对话框）
- 实现 NavigationHelper（路由导航）
工具类
- 移植 PermissionHelper
- 移植 UtilManager
- 移植 CrashHelper（崩溃收集）
业务功能
- 移植 VersionUpdateManager
- 实现版本更新对话框（ArkUI）
- 移植 SocketIOManager

阶段四：能力层模块（2-3周）

目标： 实现各能力模块

任务清单：

SocketIO 能力
- 实现 SocketIO 客户端（基于 HarmonyOS WebSocket）
- 实现 SocketIORepository
- 集成 Token 自动获取
其他能力
- BLE 能力（基于 @kit.ConnectivityKit）
- NFC 能力（基于 @kit.ConnectivityKit）
- 二维码能力（基于 @kit.BarcodeKit）
- 推送能力（基于极光推送）
- 分享能力（友盟分享 + 微信 SDK）
  - ⚠️ 必须参考友盟官方文档：
  - 友盟分享 HarmonyOS 集成指南
  - 友盟分享 HarmonyOS 微信平台配置
  - 友盟分享 HarmonyOS 回调处理
  - 友盟分享 HarmonyOS 常见问题

阶段五：业务层实现（2-3周）

目标： 实现业务页面和功能

任务清单：

应用初始化
- 实现 AppInitializer
- 实现 EntryAbility 初始化
- 配置应用启动流程
业务页面
- 实现主页面
- 实现各业务功能页面
- 集成能力模块
测试和优化
- 功能测试
- 性能优化
- UI/UX 优化

🔧 技术实现细节

1. 模块依赖管理

HarmonyOS 使用 oh-package.json5：

// base-core/oh-package.json5
{
  "name": "@xdz/base-core",
  "version": "1.0.0",
  "description": "基础设施层",
  "main": "src/main/ets/index.ets",
  "dependencies": {
    "@kit.PerformanceAnalysisKit": "^1.0.0",
    "@kit.NetworkKit": "^1.0.0",
    "@kit.PreferencesKit": "^1.0.0"
  }
}

// base-common/oh-package.json5
{
  "name": "@xdz/base-common",
  "version": "1.0.0",
  "dependencies": {
    "@xdz/base-core": "file:../base-core"
  }
}

2. 存储实现示例

// base-core/src/main/ets/core/storage/StorageImpl.ets
import { preferences } from '@kit.PreferencesKit';

export class StorageImpl implements IStorage {
  private static instance: StorageImpl | null = null;
  private dataPreferences: preferences.Preferences | null = null;
  
  static async init(context: Context): Promise<void> {
    if (!this.instance) {
      this.instance = new StorageImpl();
      this.instance.dataPreferences = await preferences.getPreferences(context, 'xdz_storage_prefs');
    }
  }
  
  async putString(key: string, value: string): Promise<void> {
    await this.dataPreferences?.put(key, value);
    await this.dataPreferences?.flush();
  }
  
  async getString(key: string, defaultValue: string = ''): Promise<string> {
    return await this.dataPreferences?.get(key, defaultValue) ?? defaultValue;
  }
  
  // ... 其他方法
}

3. 网络请求封装示例

// base-core/src/main/ets/core/network/NetworkManager.ets
import { http } from '@kit.NetworkKit';

export class NetworkManager {
  private static instance: NetworkManager | null = null;
  private httpRequest: http.HttpRequest | null = null;
  
  static getInstance(): NetworkManager {
    if (!this.instance) {
      this.instance = new NetworkManager();
    }
    return this.instance;
  }
  
  async request<T>(url: string, options: http.RequestOptions): Promise<T> {
    return new Promise((resolve, reject) => {
      http.createHttp().request(url, options)
        .then((response: http.HttpResponse) => {
          const data = JSON.parse(response.result.toString());
          resolve(data as T);
        })
        .catch((error: Error) => {
          reject(error);
        });
    });
  }
}

4. UI 页面基类示例

// base-common/src/main/ets/common/ui/BasePage.ets
import { Component } from '@kit.ArkUI';

@Component
export abstract class BasePage {
  // 页面状态管理
  protected loading: boolean = false;
  protected error: string | null = null;
  
  // 生命周期方法（与 Android 保持一致）
  onPageShow(): void {
    // 页面显示
  }
  
  onPageHide(): void {
    // 页面隐藏
  }
  
  // 通用方法
  protected showLoading(): void {
    this.loading = true;
  }
  
  protected hideLoading(): void {
    this.loading = false;
  }
  
  protected showError(message: string): void {
    this.error = message;
  }
}

5. 路由导航封装示例

// base-common/src/main/ets/common/router/NavigationHelper.ets
import { router } from '@kit.ArkUI';

export class NavigationHelper {
  // 基础跳转
  static navigate(path: string, params?: Record<string, Object>): void {
    router.pushUrl({
      url: path,
      params: params
    });
  }
  
  // 带结果回调跳转
  static navigateForResult(
    path: string,
    params: Record<string, Object>,
    onResult: (result: Object) => void
  ): void {
    router.pushUrl({
      url: path,
      params: params
    }).then(() => {
      // 监听返回结果
      router.addObserver({
        onResult: (result: router.Result) => {
          onResult(result);
        }
      });
    });
  }
}

⚠️ 特殊功能处理

1. 微信分享回调处理（重要）

Android 版本的特殊性：

在 Android 版本中，微信分享回调 Activity（WXEntryActivity）必须放在 base-core 模块中，原因如下：

微信 SDK 要求：微信 SDK 要求回调 Activity 必须在应用包名的 wxapi 子包下
- 包名必须是：com.narutohuo.xindazhou.wxapi.WXEntryActivity
- 不能使用模块的 namespace（如 com.narutohuo.xindazhou.core.wxapi）
架构设计：
- 文件位置：base-core/src/main/java/com/narutohuo/xindazhou/wxapi/WXEntryActivity.kt
- 包名使用：com.narutohuo.xindazhou.wxapi（应用包名，不是模块 namespace）
- 通过 ARouter 依赖注入获取 IShareCallback 实现，实现解耦

AndroidManifest 配置：

<!-- base-core/src/main/AndroidManifest.xml -->
<activity
   android:name="com.narutohuo.xindazhou.wxapi.WXEntryActivity"
   android:exported="true"
   android:theme="@android:style/Theme.Translucent.NoTitleBar" />

HarmonyOS 版本的处理方案：

⚠️ 重要：需要参考友盟官方文档进行配置

友盟分享 SDK 已支持 HarmonyOS，但具体的回调处理方式需要参考友盟官方文档：

友盟官方文档：
回调机制：
- HarmonyOS 使用 Want 和 Ability 处理回调（与 Android 的 Activity 不同）
- 需要在 module.json5 中配置回调 Ability
- 具体配置方式请参考友盟官方文档
实现位置：
- 文件位置：base-core/src/main/ets/wxapi/WXEntryAbility.ets（待确认）
- 包名使用：应用包名（与 Android 保持一致）
- 具体实现方式请参考友盟官方文档
module.json5 配置：
- 需要在 module.json5 中添加微信相关的配置
- 需要配置 querySchemes 以判断是否安装微信（避免异常状态码 17700056）
- 具体配置请参考友盟官方文档

注意事项：

⚠️ 必须参考友盟官方文档：HarmonyOS 的微信分享回调处理方式与 Android 不同，需要严格按照友盟官方文档进行配置
⚠️ 配置 querySchemes：在 module.json5 中需要添加微信的 querySchemes 配置，否则可能返回异常状态码 17700056
✅ HarmonyOS 中也需要将微信回调 Ability 放在 base-core 模块（待确认）
✅ 包名使用应用包名，保持与 Android 一致
✅ 友盟分享 SDK 已支持 HarmonyOS，但具体实现方式需要参考官方文档

2. 极光推送集成

Android 版本：

使用极光推送 SDK
在 capability-push 模块中实现 IPushService 接口

HarmonyOS 版本：

极光推送已支持 HarmonyOS（通过华为开发者联盟审核）
继续使用极光推送 SDK
在 capability-push 模块中实现 IPushService 接口
需要确认极光推送 HarmonyOS SDK 的集成方式

集成步骤：

确认极光推送 HarmonyOS SDK 版本和集成方式
在 capability-push/oh-package.json5 中添加依赖
实现 IPushService 接口
配置推送权限和回调

3. 友盟分享集成

Android 版本：

使用友盟分享 SDK
在 capability-share 模块中实现 IShareService 接口
支持微信、QQ、微博等平台

HarmonyOS 版本：

✅ 友盟分享 SDK 已支持 HarmonyOS
继续使用友盟分享 SDK（与 Android 保持一致）
需要参考友盟官方文档进行集成：

集成要点：

在 module.json5 中配置微信相关的 querySchemes（避免异常状态码 17700056）
配置微信分享回调 Ability（参考友盟文档）
初始化友盟分享 SDK（与 Android 类似，但需要适配 HarmonyOS API）
实现分享回调处理（使用 Ability 替代 Activity）

🎨 HarmonyOS 特色功能

1. 分布式能力

Android 无对应功能，HarmonyOS 独有：

分布式数据管理
分布式设备管理
跨设备协同

建议：

在 base-core 中预留分布式能力接口
在 capability-xxx 中实现具体分布式功能

2. 卡片能力

Android Widget 的 HarmonyOS 版本：

桌面卡片
服务卡片

建议：

在 base-common 中封装卡片管理
提供统一的卡片创建和管理接口

3. 原子化服务

HarmonyOS 特色：

免安装运行
跨设备流转

建议：

考虑将部分功能模块原子化
在架构中预留原子化服务支持

⚠️ 注意事项

1. 语言差异

Android: Kotlin（JVM）
HarmonyOS: ArkTS（TypeScript 超集）

处理方式：

业务逻辑尽量保持算法一致
UI 层完全重写
接口定义保持一致

2. 异步处理

Android: Coroutines + Flow
HarmonyOS: Promise + async-await

处理方式：

封装异步处理，提供统一接口
保持业务逻辑层代码结构一致

3. 依赖管理

Android: Gradle + Maven
HarmonyOS: oh-package.json5 + npm

处理方式：

使用 oh-package.json5 管理依赖
本地模块使用 file:../ 引用

4. 构建系统

Android: Gradle
HarmonyOS: Hvigor

处理方式：

使用 Hvigor 构建系统
配置构建脚本

📊 移植优先级

高优先级（必须）

✅ base-core - 基础设施层
✅ base-common/auth - 认证模块
✅ base-common/network - 网络封装
✅ base-common/storage - 存储封装
✅ capability-socketio - SocketIO 能力

中优先级（重要）

⚠️ base-common/ui - UI 基础类
⚠️ base-common/version - 版本更新
⚠️ base-common/launch - 启动管理
⚠️ capability-ble - BLE 能力
⚠️ capability-nfc - NFC 能力

低优先级（可选）

⚠️ capability-push - 推送能力（极光推送，需确认 HarmonyOS SDK）
⚠️ capability-share - 分享能力（友盟分享，需确认 HarmonyOS 支持）
⏸️ capability-qrcode - 二维码能力

📅 时间估算

阶段	时间	说明
阶段一：基础设施搭建	1-2周	建立基础架构
阶段二：核心业务功能	2-3周	认证、网络、存储
阶段三：UI 和工具封装	2-3周	UI 基础类、工具类
阶段四：能力层模块	2-3周	SocketIO、BLE、NFC 等
阶段五：业务层实现	2-3周	业务页面、测试优化
总计	9-14周	约 2-3.5 个月

✅ 验收标准

功能验收

所有核心功能正常运行
登录/注册流程完整
网络请求正常
存储功能正常
SocketIO 连接正常

性能验收

页面加载速度 < 1s
网络请求响应时间 < 2s
内存占用合理
无内存泄漏

代码质量

代码结构清晰
注释完整
无编译警告
符合 HarmonyOS 开发规范

📚 参考资料

🔄 后续优化

短期优化（1-2个月）

性能优化
UI/UX 优化
错误处理完善
日志系统完善

长期优化（3-6个月）

分布式能力集成
卡片能力开发
原子化服务支持
跨设备协同功能

📝 总结

本移植方案保持与 Android 版本架构一致，同时充分利用 HarmonyOS 的特色能力。通过分阶段实施，确保每个阶段可独立验证，降低移植风险。

关键成功因素：

✅ 保持架构一致性
✅ 充分利用鸿蒙特色
✅ 代码复用最大化
✅ 渐进式迁移

文档版本： v1.0
创建时间： 2024-12
最后更新： 2024-12

移植方案.md 26 KB Histórico Raw

新大洲智能车控 HarmonyOS 移植方案

📋 项目概述

🎯 移植目标

核心原则

🏗️ 架构对比分析

Android 架构

HarmonyOS 目标架构

📦 模块结构设计

1. base-core（基础设施层）

2. base-common（业务封装层）

3. capability-xxx（能力层）

4. entry（业务层）

🔄 关键技术映射

1. 存储系统

2. 网络请求

3. UI 框架

4. 路由导航

5. 生命周期

6. 权限管理

📝 移植步骤

阶段一：基础设施搭建（1-2周）

阶段二：核心业务功能（2-3周）

阶段三：UI 和工具封装（2-3周）

阶段四：能力层模块（2-3周）

阶段五：业务层实现（2-3周）

🔧 技术实现细节

1. 模块依赖管理

2. 存储实现示例

3. 网络请求封装示例

4. UI 页面基类示例

5. 路由导航封装示例

⚠️ 特殊功能处理

1. 微信分享回调处理（重要）

2. 极光推送集成

3. 友盟分享集成

🎨 HarmonyOS 特色功能

1. 分布式能力

2. 卡片能力

3. 原子化服务

⚠️ 注意事项

1. 语言差异

2. 异步处理

3. 依赖管理

4. 构建系统

📊 移植优先级

高优先级（必须）

中优先级（重要）

低优先级（可选）

📅 时间估算

✅ 验收标准

功能验收

性能验收

代码质量

📚 参考资料

🔄 后续优化

短期优化（1-2个月）

长期优化（3-6个月）

📝 总结

移植方案.md 26 KB

Histórico Raw