105 lines
6.0 KiB
Markdown
105 lines
6.0 KiB
Markdown
# 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）
|
||
|
||
1. **严格类型 Strict types** — 禁止 `any` / `@ts-ignore` / `@ts-expect-error`；类型搞不定说明设计有问题。
|
||
No `any` / `@ts-ignore` / `@ts-expect-error`. If types won't work, the design is wrong.
|
||
2. **声明式 UI Declarative UI** — 用状态驱动渲染，禁止命令式直接改 UI。
|
||
Drive UI via state; never mutate UI imperatively.
|
||
3. **命名 Naming** — 组件/Ability `PascalCase`（文件 `.ets`）；变量/函数/属性 `camelCase`；常量 `UPPER_SNAKE_CASE`。
|
||
4. **资源 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.
|
||
5. **分层 Layering** — 页面只编排；业务逻辑放 `viewmodel/`，数据放 `data/`（repository/api），模型放 `model/`，复用组件放 `view/`（通用下沉 `uikit/`）。
|
||
Pages orchestrate only; logic → `viewmodel/`, data → `data/`, models → `model/`, reusable components → `view/` (shared → `uikit/`).
|
||
6. **安全 Security** — 遵守 `code-linter.json5` 的 `@security/*` 规则（禁用不安全哈希/AES 等）。
|
||
7. **改后必验证 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` |
|
||
| UI 主题与图标 Theme & Icons | `docs/ui-theme.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.
|