# Architecture（架构）

HarmonyOS NEXT 单 HAP 应用，API 22（HarmonyOS 6.0）。技术栈：ArkTS + ArkUI 声明式 UI + hvigor。
Single-HAP HarmonyOS NEXT app, API 22 (HarmonyOS 6.0). Stack: ArkTS + ArkUI declarative UI + hvigor.

## 模块结构 Module Structure

- **AppScope/** — 应用级信息：`app.json5` 里定义 `bundleName`（`com.mingyuan.harmony_client`）、应用图标/标签（`$media:layered_image` / `$string:app_name`）。
- **entry/** — 唯一主模块（HAP）。`module.json5` 声明 Ability、权限、入口。

## Ability 生命周期 Ability Lifecycle

**EntryAbility**（`entry/src/main/ets/entryability/EntryAbility.ets`）是应用入口，继承 `UIAbility`。关键回调：

| 回调 Callback | 用途 Purpose |
|--------------|-------------|
| `onCreate` | Ability 创建，初始化状态（**此时不要做 UI 操作**） |
| `onWindowStageCreate` | 窗口创建，在这里 `loadContent('pages/Index')` 加载首页 |
| `onForeground` / `onBackground` | 前后台切换 |
| `onDestroy` | 销毁，释放资源 |

**EntryBackupAbility** — 应用备份扩展 Ability（备份/恢复数据）。

## 页面与路由 Pages & Routing

- 页面组件用 `@Entry` 装饰，在 `entry/src/main/resources/base/profile/main_pages.json` 注册。
- 页面跳转：`router.pushUrl()`（栈式导航），或 `Navigation` 组件（推荐，用于复杂导航）。

## 目录分层 Layering Convention

```
entry/src/main/ets/
├── entryability/        # Ability 入口（生命周期）
├── entrybackupability/  # 备份扩展
├── pages/               # 页面（@Entry 组件，只做 UI 编排）
├── components/          # 可复用 UI 组件（@Component / @Reusable）
├── viewmodel/           # 状态管理（连接 model 与 UI）
├── service/             # 业务逻辑、数据访问（网络/存储）
├── model/               # 数据模型、类型定义
└── common/              # 公共常量、工具函数
```

依赖方向（只能从右往左引，禁止反向）：
Dependency direction (only right→left, never reverse):
`pages → viewmodel → service → model`；`components` 不依赖业务层。

## 状态管理 State Management

- 组件内：`@State`（本地）、`@Prop`（父传子单向）、`@Link`（父子双向）。
- 跨组件：`@Provide` / `@Consume`，或 `AppStorage`（全局）/ `LocalStorage`（页面级）。
- 持久化：`PersistentStorage`（简单键值）。
- 原则：**UI 由状态驱动**，不在组件外手动改 UI。

## 关键约定速查 Key Contracts

- 所有字符串/颜色/媒体走 `$r()` 资源引用。
- 页面只做 UI 编排；数据获取/业务判断在 `service/`，类型在 `model/`。
- 新增页面必须同步注册到 `main_pages.json`。