docs: harness 文档对齐新架构，忽略签名材料

docs/build-deploy.md

@@ -17,6 +17,20 @@ hvigorw assembleHap --mode module -p product=default -p buildMode=release
 
 产物通常在 `entry/build/default/outputs/` 下（`default` 为 product 名）。
 
+## 多模块构建 Multi-module Build
+
+本工程为「单 HAP + 多 HAR」：`entry/`（HAP）+ `common/`（HAR）+ `uikit/`（HAR）。
+
+- HAR（`common`/`uikit`）作为 `entry` 的依赖，构建 entry 时会**自动先编译**依赖的 HAR，正常开发只需构建 entry。
+- 任务类型：HAP 用 `assembleHap`，HAR 用 `assembleHar`。
+- 构建整个工程用 `--mode project`（按依赖顺序构建全部模块）；构建单个模块用 `--mode module`。
+- 模块注册：根 `build-profile.json5` 的 `modules`；模块间依赖：各自 `oh-package.json5` 的 `dependencies` 用 `file:../xxx` 声明。
+
+**HAR 配置要点（易错）**：
+- `module.json5` 的 `type` 必须是 `har`（**不是** `shared`——`shared` 对应 HSP，会要求 `hspTasks`）。
+- `oh-package.json5` 的 `main: "Index.ets"` 指向**模块根目录**的 `Index.ets`（该文件 `export * from './src/main/ets/Index.ets'` 转发公共 API）。
+- 权限（如 `ohos.permission.INTERNET`）只声明在 HAP 的 `module.json5` 的 `requestPermissions`；HAR 不声明权限。
+
 ## 签名 Signing
 
 `build-profile.json5` 里 `signingConfigs` 目前为**空**，且 `products[].signingConfig` 引用了 `"default"` —— **签名尚未配置**。

docs/conventions.md

@@ -21,25 +21,33 @@ ArkTS（TypeScript 的超集，HarmonyOS 严格类型方言）+ ArkUI 声明式
 ## 声明式 UI 与状态 Declarative UI & State
 
 - UI 由状态驱动：改状态 → 自动重渲染，禁止命令式直接改 UI。
-- 状态装饰器选择：
-  - 局部状态 `@State`
-  - 父子传递 `@Prop`（单向）/ `@Link`（双向）
-  - 跨层 `@Provide` / `@Consume`
-- 避免不必要的重渲染：状态粒度要细，不要一个 `@State` 装一整个大对象。
+- 状态管理**全量使用 StateManagement V2**（禁用 V1 装饰器）：
+  - 组件/页面 `@ComponentV2`
+  - 局部状态 `@Local`
+  - 父子传递 `@Param`（单向输入）/ `@Event`（子→父回调，**不用 `@Link`**）
+  - 类可观察 `@ObservedV2` + `@Trace`（字段级精准刷新）
+  - 跨层共享 `@Provider` / `@Consumer`；变化监听 `@Monitor`
+  - 全局/持久化 `AppStorageV2` / `PersistenceV2`
+- 避免不必要的重渲染：`@Trace` 字段粒度要细，不要一个大对象整体刷新。
 
 ## 资源 Resources
 
-- 字符串、颜色、媒体一律 `$r('app.xxx')`（定义在 `resources/base/element/`）。
-- 禁止在 `.ets` 里硬编码字符串、颜色值、路径。
+- 颜色 / 间距 / 字号统一走 `uikit/theme/Theme.ets` 的 token（`AppColor` / `AppSpacing` / `AppFontSize`），禁止在组件里散落颜色/尺寸魔法值。
+- 用户可见文案：优先 `$r('app.string.xxx')`（便于国际化）；临时/演示文案可内联，正式功能应收口到资源。
+- 图片/图标等媒体：`$r('app.media.xxx')`。
 
 ## 组件化 Components
 
-- 页面：`@Entry` 组件，放 `pages/`。
-- 复用组件：`@Component` 或 `@Reusable`（长列表复用），放 `components/`，通过 `@Prop`/事件回调与外界通信，不直接依赖业务层。
+- 页面：`@Entry @ComponentV2`，放 `pages/`，仅编排（组合 view + viewmodel，不含业务逻辑）。
+- 业务复用组件：`@ComponentV2`，放 `view/`，通过 `@Param`（输入）/ `@Event`（回调）与外界通信，不直接依赖业务层。
+- 跨模块通用组件：下沉到 `uikit/`（`uikit/src/main/ets/components/`）。
+- 长列表复用用 `@Reusable`。
 
 ## 分层与依赖方向 Layering
 
-`pages → viewmodel → service → model`。禁止反向依赖（如 `model` import `service`）。
+`pages → viewmodel → data(repository/api) → model`。禁止反向依赖（如 `model` import `repository`）。
+- `viewmodel` 只依赖 `data/repository` 的抽象契约；`repository` 实现依赖 `data/api` + `common` 网络层。
+- 跨模块依赖：`entry → common / uikit`；`common`、`uikit` 相互独立，禁止反向/循环依赖。
 架构越界由约定 + 人工审查把关（ArkTS 侧暂无现成的依赖方向 linter）。
 
 ## 安全 Security

docs/testing.md

@@ -6,7 +6,7 @@
 
 | 类型 Kind | 目录 Dir | 说明 Notes |
 |----------|---------|-----------|
-| 本地单元测试 Local unit | `entry/src/test/` | 不依赖设备，跑纯逻辑（service/model 等） |
+| 本地单元测试 Local unit | `entry/src/test/` | 不依赖设备，跑纯逻辑（viewmodel/data/model 等） |
 | 设备集成测试 Device test | `entry/src/ohosTest/` | 依赖真机/模拟器，跑 Ability/UI/系统能力 |
 
 已有示例文件：`LocalUnit.test.ets`、`List.test.ets`（单测）；`Ability.test.ets`、`List.test.ets`（设备测试）。
@@ -17,7 +17,7 @@
 import { describe, it, expect } from '@ohos/hypium';
 
 export default function exampleTest() {
-  describe('UserService', () => {
+  describe('UserRepository', () => {
     it('should_return_trimmed_name', 0, () => {
       expect(formatName('  alice  ')).assertEqual('alice');
     });
@@ -37,7 +37,7 @@ export default function exampleTest() {
 
 ## 约定 Conventions
 
-- 每个 `service/`、`model/` 的新逻辑都要有对应的本地单测。
+- 每个 `viewmodel/`、`data/repository/`、`model/` 的新逻辑都要有对应的本地单测。
 - 涉及 UI/系统能力/Ability 生命周期 → 设备测试（`ohosTest/`）。
 - mock 用 `@ohos/hamock`，不要为了测试改生产代码结构。
 - 改动后至少跑受影响的测试再提交。