harmony-client

HarmonyOS NEXT 应用（鸿蒙客户端）。ArkTS + ArkUI 声明式 UI，hvigor 构建，DevEco Studio 开发。 HarmonyOS NEXT app. ArkTS + ArkUI declarative UI, hvigor build, DevEco Studio.

Quick Start

主路径：用 DevEco Studio 打开本目录，首次打开自动同步依赖（hvigor 插件 + oh_modules）。 Primary: open this folder in DevEco Studio; first open auto-syncs dependencies.
命令行构建（hvigorw wrapper 由 DevEco 首次同步生成）： hvigorw assembleHap --mode module -p product=default -p buildMode=debug
测试：本地单测 entry/src/test/，设备测试 entry/src/ohosTest/。见 docs/testing.md。

Architecture Overview

单 HAP + 多 HAR 模块化应用：entry/（HAP，应用壳 + 业务）、common/（HAR，基础设施）、uikit/（HAR，通用 UI）。 Single-HAP + multi-HAR: entry/ (HAP shell + business), common/ (HAR infra), uikit/ (HAR shared UI). 状态管理全量 StateManagement V2（@ComponentV2/@Local/@Param/@Event/@ObservedV2/@Trace）；导航用 Navigation + NavPathStack。详见 docs/architecture.md。

Directory Structure

harmony-client/
├── AppScope/                 # 应用级配置（bundleName、应用图标/标签）
├── entry/                    # HAP 应用壳 + 业务（唯一入口）
│   └── src/
│       ├── main/
│       │   ├── ets/
│       │   │   ├── entryability/        # 应用入口 Ability（依赖装配）
│       │   │   ├── entrybackupability/  # 备份扩展 Ability
│       │   │   ├── router/              # 路由（AppRouter + RouteMap）
│       │   │   ├── di/                  # 依赖注入（ServiceLocator）
│       │   │   ├── model/               # 领域模型（@ObservedV2 + @Trace）
│       │   │   ├── data/                # 数据层（api / repository）
│       │   │   ├── viewmodel/           # 视图模型（@ObservedV2 三态）
│       │   │   ├── view/                # 业务复用组件
│       │   │   └── pages/               # 页面（@Entry @ComponentV2，仅编排）
│       │   ├── resources/    # 资源（字符串/媒体，用 $r() 引用）
│       │   └── module.json5  # 模块清单（Ability 声明、权限）
│       ├── test/             # 本地单元测试（hypium）
│       ├── ohosTest/         # 设备集成测试（hypium）
│       └── mock/             # mock 配置
├── common/                   # HAR 基础设施（网络/日志/状态/工具）
├── uikit/                    # HAR 通用 UI 组件库 + 主题 token
├── build-profile.json5       # 构建/签名/产品/模块配置
├── code-linter.json5         # 代码规范（TS ESLint + 安全/性能规则）
├── hvigorfile.ts             # hvigor 构建入口
├── oh-package.json5          # 依赖声明（hypium / hamock）
└── docs/                     # 系统记录（见下方文档地图）

Key Conventions（硬规则 / Hard Rules）

严格类型 Strict types — 禁止 any / @ts-ignore / @ts-expect-error；类型搞不定说明设计有问题。 No any / @ts-ignore / @ts-expect-error. If types won't work, the design is wrong.
声明式 UI Declarative UI — 用状态驱动渲染，禁止命令式直接改 UI。 Drive UI via state; never mutate UI imperatively.
命名 Naming — 组件/Ability PascalCase（文件 .ets）；变量/函数/属性 camelCase；常量 UPPER_SNAKE_CASE。
资源 Resources — 颜色/间距/字号走 uikit/theme/Theme.ets 的 token；用户可见文案优先 $r('app.string.xxx')；媒体 $r('app.media.xxx')。禁止组件内散落魔法值。 Colors/spacing/fonts via uikit/theme/Theme.ets tokens; copy via $r('app.string.xxx'); media via $r('app.media.xxx'). No scattered magic values.
分层 Layering — 页面只编排；业务逻辑放 viewmodel/，数据放 data/（repository/api），模型放 model/，复用组件放 view/（通用下沉 uikit/）。 Pages orchestrate only; logic → viewmodel/, data → data/, models → model/, reusable components → view/ (shared → uikit/).
安全 Security — 遵守 code-linter.json5 的 @security/* 规则（禁用不安全哈希/AES 等）。
改后必验证 Verify after change — 每次改动跑 lint + 相关测试，见 docs/testing.md。

Documentation Map（文档地图）

主题 Topic	文件 File
架构 Architecture	`docs/architecture.md`
编码规范 Conventions	`docs/conventions.md`
测试 Testing	`docs/testing.md`
构建/签名/部署 Build & Deploy	`docs/build-deploy.md`
分支模型与 Git 规范 Git Workflow	`docs/git-workflow.md`

Common Tasks

加页面 Add a page → entry/src/main/ets/pages/（Navigation 路由则加 router/RouteMap.ets）
加复用组件 Reusable component → entry/src/main/ets/view/（跨模块通用 → uikit/src/main/ets/components/）
写业务逻辑 Business logic → entry/src/main/ets/viewmodel/ + entry/src/main/ets/data/
加数据模型 Data model → entry/src/main/ets/model/
跑单测 Run tests → docs/testing.md

Agent Permissions（权限边界）

允许 Allowed

创建/修改 entry/src/main/ets/ 与 docs/
运行测试与 lint
安装 devDependencies
建 feature 分支（feature/xxx）

禁止 Forbidden

修改签名配置（build-profile.json5 的 signingConfigs）
删除测试文件
push 到 main 或 dev（一律走 PR）
往 local.properties / .env 写真实密钥
未经批准安装生产依赖

工作状态 / Working State

跨会话进度记录在 docs/；若一项决策重要，必须写入文件（口头约定=丢失的上下文）。 Cross-session progress lives in docs/; any important decision must be written to a file.

6.0 KiB Raw Blame History Unescape Escape