harness: initial project setup
This commit is contained in:
andy
58
docs/architecture.md
Normal file
58
docs/architecture.md
Normal file
@@ -0,0 +1,58 @@
|
||||
# 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`。
|
||||
43
docs/build-deploy.md
Normal file
43
docs/build-deploy.md
Normal file
@@ -0,0 +1,43 @@
|
||||
# Build & Deploy（构建与部署）
|
||||
|
||||
构建系统：hvigor（HarmonyOS 官方构建工具），配置见 `hvigor/`、`hvigorfile.ts`、`build-profile.json5`。
|
||||
|
||||
## 构建 / 运行 Build & Run
|
||||
|
||||
- **主路径**：DevEco Studio → Build / Run（GUI）。首次打开自动同步依赖。
|
||||
- 命令行（`hvigorw` wrapper 由 DevEco 首次同步生成）：
|
||||
|
||||
```bash
|
||||
# 构建 debug HAP
|
||||
hvigorw assembleHap --mode module -p product=default -p buildMode=debug
|
||||
|
||||
# 构建 release HAP
|
||||
hvigorw assembleHap --mode module -p product=default -p buildMode=release
|
||||
```
|
||||
|
||||
产物通常在 `entry/build/default/outputs/` 下（`default` 为 product 名）。
|
||||
|
||||
## 签名 Signing
|
||||
|
||||
`build-profile.json5` 里 `signingConfigs` 目前为**空**，且 `products[].signingConfig` 引用了 `"default"` —— **签名尚未配置**。
|
||||
要跑真机/模拟器需先配置签名：
|
||||
- DevEco Studio → File → Project Structure → Signing Configs → 勾选自动签名（登录华为账号）。
|
||||
- 或手动配置 `.p12` + `.cer` / `.p7b`。
|
||||
|
||||
> 该文件的签名部分属于 **Agent 禁止修改** 范围（见 `AGENTS.md`）。
|
||||
|
||||
## 产品与构建模式 Products & Build Modes
|
||||
|
||||
- `products`：当前只有一个 `default`（`targetSdkVersion 6.0.2(22)`，`runtimeOS: HarmonyOS`）。
|
||||
- `buildModeSet`：`debug` / `release`。
|
||||
|
||||
## 部署 Deploy
|
||||
|
||||
1. 配置签名（见上）。
|
||||
2. 连接真机（开启开发者模式 + USB 调试）或启动模拟器。
|
||||
3. DevEco Studio 选择设备 → Run。
|
||||
|
||||
## 环境环境变量 / 本地配置
|
||||
|
||||
- `local.properties`：本机 SDK 路径等，**已 gitignore，勿提交，勿写密钥**。
|
||||
- 依赖锁：`oh-package-lock.json5`，提交以固定依赖版本。
|
||||
62
docs/conventions.md
Normal file
62
docs/conventions.md
Normal file
@@ -0,0 +1,62 @@
|
||||
# Conventions（编码规范）
|
||||
|
||||
ArkTS（TypeScript 的超集，HarmonyOS 严格类型方言）+ ArkUI 声明式 UI。
|
||||
|
||||
## 命名 Naming
|
||||
|
||||
| 元素 Element | 规则 Rule | 示例 Example |
|
||||
|-------------|----------|-------------|
|
||||
| 组件 / Ability | `PascalCase` | `LoginPage`, `EntryAbility` |
|
||||
| 文件 | 与组件同名 `.ets` | `LoginPage.ets` |
|
||||
| 变量 / 函数 / 属性 | `camelCase` | `userName`, `fetchData()` |
|
||||
| 常量 | `UPPER_SNAKE_CASE` | `MAX_RETRY_COUNT` |
|
||||
| 布尔变量 | `is`/`has`/`can` 前缀 | `isLoading`, `hasError` |
|
||||
|
||||
## 严格类型 Strict Typing
|
||||
|
||||
- **禁止** `any`、`@ts-ignore`、`@ts-expect-error`。
|
||||
- 类型搞不定 = 设计有问题，重构类型而不是绕过它。
|
||||
- 优先 `interface` / `enum`，复杂类型放 `model/`。
|
||||
|
||||
## 声明式 UI 与状态 Declarative UI & State
|
||||
|
||||
- UI 由状态驱动：改状态 → 自动重渲染，禁止命令式直接改 UI。
|
||||
- 状态装饰器选择：
|
||||
- 局部状态 `@State`
|
||||
- 父子传递 `@Prop`（单向）/ `@Link`（双向）
|
||||
- 跨层 `@Provide` / `@Consume`
|
||||
- 避免不必要的重渲染：状态粒度要细，不要一个 `@State` 装一整个大对象。
|
||||
|
||||
## 资源 Resources
|
||||
|
||||
- 字符串、颜色、媒体一律 `$r('app.xxx')`（定义在 `resources/base/element/`）。
|
||||
- 禁止在 `.ets` 里硬编码字符串、颜色值、路径。
|
||||
|
||||
## 组件化 Components
|
||||
|
||||
- 页面：`@Entry` 组件，放 `pages/`。
|
||||
- 复用组件：`@Component` 或 `@Reusable`（长列表复用），放 `components/`，通过 `@Prop`/事件回调与外界通信，不直接依赖业务层。
|
||||
|
||||
## 分层与依赖方向 Layering
|
||||
|
||||
`pages → viewmodel → service → model`。禁止反向依赖（如 `model` import `service`）。
|
||||
架构越界由约定 + 人工审查把关（ArkTS 侧暂无现成的依赖方向 linter）。
|
||||
|
||||
## 安全 Security
|
||||
|
||||
`code-linter.json5` 已启用 `@security/*` 规则，**改动不得引入不安全算法**：
|
||||
- 禁用不安全哈希（MD5/SHA1）、不安全 AES 模式、3DES、弱 RSA/DH 密钥等。
|
||||
- 需要加密时优先系统安全 API（如 `@ohos.security.cryptoFramework` 的安全模式）。
|
||||
|
||||
## 性能 Performance
|
||||
|
||||
`code-linter.json5` 已启用 `@performance/recommended`：
|
||||
- 长列表用 `LazyForEach` + `@Reusable`，不要 `ForEach` 渲染大量节点。
|
||||
- 避免在 `build()` 里做重计算/创建新对象。
|
||||
- 大图/列表项懒加载，图片用合适的缓存策略。
|
||||
|
||||
## 改动后验证 Verify After Change
|
||||
|
||||
- 跑 lint：DevEco 里 Code Linter，或 hvigor 对应任务。
|
||||
- 跑相关测试：见 `docs/testing.md`。
|
||||
- 提交前确认 `code-linter.json5` 无新增 error。
|
||||
43
docs/testing.md
Normal file
43
docs/testing.md
Normal file
@@ -0,0 +1,43 @@
|
||||
# Testing（测试）
|
||||
|
||||
测试框架：`@ohos/hypium`（断言 + 用例组织），`@ohos/hamock`（mock）。已在 `oh-package.json5` 声明。
|
||||
|
||||
## 两类测试 Two Test Kinds
|
||||
|
||||
| 类型 Kind | 目录 Dir | 说明 Notes |
|
||||
|----------|---------|-----------|
|
||||
| 本地单元测试 Local unit | `entry/src/test/` | 不依赖设备，跑纯逻辑（service/model 等） |
|
||||
| 设备集成测试 Device test | `entry/src/ohosTest/` | 依赖真机/模拟器，跑 Ability/UI/系统能力 |
|
||||
|
||||
已有示例文件：`LocalUnit.test.ets`、`List.test.ets`（单测）；`Ability.test.ets`、`List.test.ets`（设备测试）。
|
||||
|
||||
## 写法（hypium 语法）
|
||||
|
||||
```typescript
|
||||
import { describe, it, expect } from '@ohos/hypium';
|
||||
|
||||
export default function exampleTest() {
|
||||
describe('UserService', () => {
|
||||
it('should_return_trimmed_name', 0, () => {
|
||||
expect(formatName(' alice ')).assertEqual('alice');
|
||||
});
|
||||
});
|
||||
}
|
||||
```
|
||||
|
||||
- 用例名用 `should_xxx` 描述预期行为。
|
||||
- **测试即规格（test as spec）**：测试描述的是"应该发生什么"，agent 读测试即可理解预期行为。
|
||||
|
||||
## 运行 Run
|
||||
|
||||
- **DevEco Studio**：右键 `test/` 或 `ohosTest/` 目录 → Run Tests（推荐，主路径）。
|
||||
- 命令行（hvigor）：
|
||||
- 本地单测：`hvigorw test` 相关 task
|
||||
- 设备测试：`hvigorw test`（需连接设备/模拟器）
|
||||
|
||||
## 约定 Conventions
|
||||
|
||||
- 每个 `service/`、`model/` 的新逻辑都要有对应的本地单测。
|
||||
- 涉及 UI/系统能力/Ability 生命周期 → 设备测试（`ohosTest/`）。
|
||||
- mock 用 `@ohos/hamock`，不要为了测试改生产代码结构。
|
||||
- 改动后至少跑受影响的测试再提交。
|
||||
Reference in New Issue
Block a user