HarmonyScaffold

鸿蒙（HarmonyOS / ArkTS）商业项目脚手架，与 CmpAppScaffold（Kotlin/Compose Multiplatform，Android/iOS）是姊妹项目：同一套"分层 + 能力门面"思路，各用各平台的主流栈。

模块结构

HarmonyScaffold/
├── AppScope/                  工程级配置与跨模块共享资源（theme_* 主题色）
├── common/        HAR         脚手架核心：日志/存储(KV+DB)/网络/图片/路由表/单例容器
├── features/
│   ├── home/     HAR         首页 tab（占位）
│   ├── browse/   HAR         逛 tab（占位）
│   ├── message/  HAR         消息 tab（占位）
│   ├── cart/     HAR         购物车 tab：wanandroid 文章分页演示（Refresh + onReachEnd + 勾选合计）
│   ├── mine/     HAR         我的 tab（占位）
│   └── login/    HAR         登录页（根栈全屏流程骨架）
└── entry/         HAP 壳      启动 Ability + 五 Tab 主壳（Navigation 根栈 + Tabs）

依赖方向单向：entry → features/* → common。

主壳形态（对标 CmpAppScaffold MainTabNavigation）

• entry/pages/Index.ets：Navigation 根栈（zrouter）宿主，栈底是五 Tab 容器（Tabs + 自定义 tabBar，底栏常驻、禁滑动切换）；
• tab 根页面由主壳直接 import 渲染（仍注册 @Route）；Tabs 切换不销毁内容，各 tab 状态天然保留（对应 CMP 多返回栈的鸿蒙实现）；tab 内出现二级页时再在 TabContent 内嵌子 Navigation；
• 登录等全局流程走根栈全屏 push；返回策略：根栈非空放行 pop → 非首页 tab 先回首页 → 首页 2 秒双击退出（Toast 提示 + terminateSelf）；
• 购物车演示链路：article/list/{page}/json 分页（LoadMoreState 状态机：LOADING 去重 / END 短路 / 空页判 End / 跨页 id 滤重），结算按钮 push 登录页（对标 CMP cart checkout → onLogin）。

能力栈（八项）

能力	选型	说明
网络	@ohos/axios 2.2.15	HttpClient 门面：统一 baseURL/超时/日志拦截器
KV 存储	@tencent/mmkv 2.4.2	KeyValueStore 接口 + MMKV 实现，preferences 版保留可一行回退
数据库	relationalStore（官方）	AppDatabase：execute/query/insert 薄封装
路由	@hzw/zrouter 1.9.0	注解路由（@Route）+ 编译期插件生成路由表，底层官方 Navigation
图片	@ohos/imageknife 3.2.10	AppImage 组件：占位图/失败图/裁剪模式收敛
序列化	class-transformer 0.5.1	plainToInstance JSON → 类实例
日志	自写 AppLogger	hilog 门面，级别可整体压
DI	自写 AppContext	手写单例装配点（鸿蒙无主流 DI 库）

状态管理用官方 ArkTS V2（@ObservedV2 / @Trace / @Computed / @ComponentV2）。

快速开始

DevEco Studio：直接打开工程根目录，默认 product 构建。真机运行需先配置自动签名（File → Project Structure → Signing Configs）。

命令行（工程无 hvigorw 包装脚本，调用 DevEco 自带工具链）：

# 构建（产出未签名 HAP：entry/build/default/outputs/default/）
PATH="/Applications/DevEco-Studio.app/Contents/tools/node/bin:$PATH" \
DEVECO_SDK_HOME=/Applications/DevEco-Studio.app/Contents/sdk \
/Applications/DevEco-Studio.app/Contents/tools/hvigor/bin/hvigorw \
  --mode module -p product=default -p buildMode=debug assembleHap \
  --parallel --incremental --daemon=false

# cart 模块单元测试（结果：features/cart/.test/default/intermediates/test/coverage_data/）
# 同上，把 assembleHap 换成：--mode module -p module=cart@default test

新增一个业务模块（HAR）的步骤

1. 复制任一 features/* 的模块骨架（oh-package.json5 / build-profile.json5 / hvigorfile.ts / src/main/module.json5 / Index.ets，以及预置空的 resources/base/profile/route_map.json）；
2. 根 build-profile.json5 的 modules 数组注册新模块；
3. entry/oh-package.json5 加 "模块名": "file:../features/模块名" 依赖（否则不打进 HAP）；
4. 页面组件加 @Route({ name: AppRoutes.XXX, useV2: true })，路由名常量加进 common 的 AppRoutes；
5. 工程根目录跑 ohpm install --all（不要在模块目录跑）。

单元测试

测试位于各 HAR 的 src/test/，用 @ohos/hypium；import 被测代码用相对路径 ../main/ets/...。当前 cart 模块 9 个用例（价格格式化、DTO 解析与 errorCode、字段合并与 hasMore、分页状态机五连、勾选合计）。

三方依赖许可

见 THIRD_PARTY_NOTICES.md。