harmony-client/docs/architecture.md

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。