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

## 📋 项目概述

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

---

## 🎯 移植目标

### 核心原则

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

---

## 🏗️ 架构对比分析

### 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周）

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

**任务清单：**

1. **创建模块结构**
   - [ ] 创建 `base-core` 模块（oh-package.json5）
   - [ ] 创建 `base-common` 模块
   - [ ] 创建 `capability-socketio` 模块
   - [ ] 配置模块依赖关系

2. **实现基础能力**
   - [ ] 实现 `ILog` 接口（基于 hilog）
   - [ ] 实现 `IStorage` 接口（基于 preferences）
   - [ ] 实现 `StorageImpl`（统一存储）
   - [ ] 实现 `NetworkManager`（基于 http）

3. **验证基础功能**
   - [ ] 存储功能测试
   - [ ] 网络请求测试
   - [ ] 日志输出测试

---

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

**目标：** 移植核心业务逻辑

**任务清单：**

1. **认证模块**
   - [ ] 移植 `TokenStore`（使用 StorageImpl）
   - [ ] 移植 `AuthManager`
   - [ ] 移植 `AuthRepository`
   - [ ] 实现登录/注册页面（ArkUI）
   - [ ] 测试登录/注册流程

2. **网络封装**
   - [ ] 封装 HTTP 请求（类似 Retrofit）
   - [ ] 实现 `ApiServiceFactory`
   - [ ] 实现 `ApiBaseRepository`
   - [ ] 统一错误处理

3. **配置管理**
   - [ ] 移植 `ConfigManager`
   - [ ] 移植 `ServerConfigManager`
   - [ ] 使用 StorageImpl 存储配置

---

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

**目标：** 完善 UI 层和工具类

**任务清单：**

1. **UI 基础类**
   - [ ] 实现 `BasePage`（页面基类）
   - [ ] 实现 `MessageHelper`（消息提示）
   - [ ] 实现 `DialogHelper`（对话框）
   - [ ] 实现 `NavigationHelper`（路由导航）

2. **工具类**
   - [ ] 移植 `PermissionHelper`
   - [ ] 移植 `UtilManager`
   - [ ] 移植 `CrashHelper`（崩溃收集）

3. **业务功能**
   - [ ] 移植 `VersionUpdateManager`
   - [ ] 实现版本更新对话框（ArkUI）
   - [ ] 移植 `SocketIOManager`

---

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

**目标：** 实现各能力模块

**任务清单：**

1. **SocketIO 能力**
   - [ ] 实现 SocketIO 客户端（基于 HarmonyOS WebSocket）
   - [ ] 实现 `SocketIORepository`
   - [ ] 集成 Token 自动获取

2. **其他能力**
   - [ ] BLE 能力（基于 @kit.ConnectivityKit）
   - [ ] NFC 能力（基于 @kit.ConnectivityKit）
   - [ ] 二维码能力（基于 @kit.BarcodeKit）
   - [ ] 推送能力（基于极光推送）
   - [ ] 分享能力（友盟分享 + 微信 SDK）
     - ⚠️ **必须参考友盟官方文档**：
       - [友盟分享 HarmonyOS 集成指南](https://developer.umeng.com/docs/128606/detail/2938159)
       - [友盟分享 HarmonyOS 微信平台配置](https://developer.umeng.com/docs/128606/detail/2938161)
       - [友盟分享 HarmonyOS 回调处理](https://developer.umeng.com/docs/128606/detail/2938160)
       - [友盟分享 HarmonyOS 常见问题](https://developer.umeng.com/docs/128606/detail/3002400)

---

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

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

**任务清单：**

1. **应用初始化**
   - [ ] 实现 `AppInitializer`
   - [ ] 实现 `EntryAbility` 初始化
   - [ ] 配置应用启动流程

2. **业务页面**
   - [ ] 实现主页面
   - [ ] 实现各业务功能页面
   - [ ] 集成能力模块

3. **测试和优化**
   - [ ] 功能测试
   - [ ] 性能优化
   - [ ] UI/UX 优化

---

## 🔧 技术实现细节

### 1. 模块依赖管理

**HarmonyOS 使用 oh-package.json5：**

```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. 存储实现示例

```typescript
// 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. 网络请求封装示例

```typescript
// 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 页面基类示例

```typescript
// 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. 路由导航封装示例

```typescript
// 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` 模块中，原因如下：

1. **微信 SDK 要求**：微信 SDK 要求回调 Activity 必须在应用包名的 `wxapi` 子包下
   - 包名必须是：`com.narutohuo.xindazhou.wxapi.WXEntryActivity`
   - 不能使用模块的 namespace（如 `com.narutohuo.xindazhou.core.wxapi`）

2. **架构设计**：
   - 文件位置：`base-core/src/main/java/com/narutohuo/xindazhou/wxapi/WXEntryActivity.kt`
   - 包名使用：`com.narutohuo.xindazhou.wxapi`（应用包名，不是模块 namespace）
   - 通过 ARouter 依赖注入获取 `IShareCallback` 实现，实现解耦

3. **AndroidManifest 配置**：
   ```xml
   <!-- 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，但具体的回调处理方式需要参考友盟官方文档：

1. **友盟官方文档**：
   - [友盟分享 HarmonyOS 集成指南](https://developer.umeng.com/docs/128606/detail/2938159)
   - [友盟分享 HarmonyOS 微信平台配置](https://developer.umeng.com/docs/128606/detail/2938161)
   - [友盟分享 HarmonyOS 回调处理](https://developer.umeng.com/docs/128606/detail/2938160)
   - [友盟分享 HarmonyOS 常见问题](https://developer.umeng.com/docs/128606/detail/3002400)

2. **回调机制**：
   - HarmonyOS 使用 `Want` 和 `Ability` 处理回调（与 Android 的 Activity 不同）
   - 需要在 `module.json5` 中配置回调 Ability
   - **具体配置方式请参考友盟官方文档**

3. **实现位置**：
   - 文件位置：`base-core/src/main/ets/wxapi/WXEntryAbility.ets`（待确认）
   - 包名使用：应用包名（与 Android 保持一致）
   - **具体实现方式请参考友盟官方文档**

4. **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 的集成方式

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

---

### 3. 友盟分享集成

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

**HarmonyOS 版本：**
- ✅ **友盟分享 SDK 已支持 HarmonyOS**
- 继续使用友盟分享 SDK（与 Android 保持一致）
- 需要参考友盟官方文档进行集成：
  - [友盟分享 HarmonyOS 集成指南](https://developer.umeng.com/docs/128606/detail/2938159)
  - [友盟分享 HarmonyOS 微信平台配置](https://developer.umeng.com/docs/128606/detail/2938161)
  - [友盟分享 HarmonyOS 回调处理](https://developer.umeng.com/docs/128606/detail/2938160)
  - [友盟分享 HarmonyOS 常见问题](https://developer.umeng.com/docs/128606/detail/3002400)

**集成要点：**
1. 在 `module.json5` 中配置微信相关的 `querySchemes`（避免异常状态码 17700056）
2. 配置微信分享回调 Ability（参考友盟文档）
3. 初始化友盟分享 SDK（与 Android 类似，但需要适配 HarmonyOS API）
4. 实现分享回调处理（使用 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 构建系统
- 配置构建脚本

---

## 📊 移植优先级

### 高优先级（必须）

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

### 中优先级（重要）

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

### 低优先级（可选）

1. ⚠️ **capability-push** - 推送能力（极光推送，需确认 HarmonyOS SDK）
2. ⚠️ **capability-share** - 分享能力（友盟分享，需确认 HarmonyOS 支持）
3. ⏸️ **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 开发规范

---

## 📚 参考资料

- [HarmonyOS 官方文档](https://developer.harmonyos.com/)
- [ArkTS 语言规范](https://developer.harmonyos.com/cn/docs/documentation/doc-references-V3/ts-overview-0000001477981205-V3)
- [ArkUI 开发指南](https://developer.harmonyos.com/cn/docs/documentation/doc-references-V3/ts-components-summary-0000001478341181-V3)
- [HarmonyOS 网络开发](https://developer.harmonyos.com/cn/docs/documentation/doc-references-V3/js-apis-http-0000001477981209-V3)

---

## 🔄 后续优化

### 短期优化（1-2个月）

1. 性能优化
2. UI/UX 优化
3. 错误处理完善
4. 日志系统完善

### 长期优化（3-6个月）

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

---

## 📝 总结

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

**关键成功因素：**
1. ✅ 保持架构一致性
2. ✅ 充分利用鸿蒙特色
3. ✅ 代码复用最大化
4. ✅ 渐进式迁移

---

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