HarmonyOS NEXT 企业级记账APP：项目规划与效果展示

本文是《HarmonyOS NEXT 企业级开发实战：30篇打造智能记账APP》系列的第 01 篇，对应 Git Tag v0.0.1。项目名称 HarmonyLedger（鸿蒙记账），定位为 HarmonyOS NEXT 企业级实战项目。

前言

随着 HarmonyOS NEXT 的正式发布，纯血鸿蒙生态进入快速发展期。ArkTS 语言与 ArkUI 声明式框架为企业级移动应用开发提供了全新的技术范式。然而，市面上的 HarmonyOS 教程多以 Demo 为主，缺少真正可落地、可维护、可扩展的 企业级项目模板。

本系列以一款完整的记账 APP 为载体，通过 30 个 Git 版本 循序渐进地构建一个企业级鸿蒙应用。每个版本对应一篇高质量技术博客、一次 Git Commit、一个 Git Tag，最终形成：

  1. 一个可运行的 HarmonyOS NEXT 企业级 APP
  2. 一个 DevEco Studio 标准工程
  3. 一套 MVVM + Repository 架构模板
  4. 一套高复用公共组件库
  5. 一套企业级工具库
  6. 30 篇可独立学习的实战博客

项目仓库：HarmonyLedger GitHub
官方文档：HarmonyOS NEXT 开发者文档

一、项目定位与目标

1.1 项目基本信息

项目属性 值
项目名称 HarmonyLedger（鸿蒙记账）
技术定位 HarmonyOS NEXT 企业级开发实战
开发语言 ArkTS
UI 框架 ArkUI（声明式）
应用模型 Stage Model
架构模式 MVVM + Repository
目标版本 HarmonyOS NEXT 5.0+
IDE 工具 DevEco Studio 5.0+
开源协议 Apache License 2.0

1.2 核心目标

HarmonyLedger 项目的核心目标可以概括为 “五个一” 工程交付物：

  • 一个 APP：真正可运行、可上架的鸿蒙记账应用
  • 一个模板：企业级架构模板，可直接复用到其他鸿蒙项目
  • 一个组件库：高复用 ArkUI 公共组件库
  • 一个工具库：企业级 ArkTS 工具类封装
  • 一套博客：30 篇高质量原创技术博客

设计哲学：拒绝 Demo 式代码。每一行代码都按企业级标准开发，追求可维护性、可扩展性与代码质量。

二、技术栈选型

2.1 核心技术栈

HarmonyLedger 采用 HarmonyOS NEXT 官方推荐的技术栈，确保技术的先进性与稳定性：

┌─────────────────────────────────────────────┐
│              HarmonyLedger 技术栈           │
├─────────────────────────────────────────────┤
│  语言层：ArkTS（TypeScript 超集）           │
│  UI 层：ArkUI 声明式框架                    │
│  模型层：Stage Model                         │
│  状态管理：@State/@Observed/@ObjectLink     │
│           AppStorage/LocalStorage            │
│  数据存储：Preferences + PersistenceV2      │
│  网络通信：HttpRequest                       │
│  图表绘制：Canvas API                        │
│  架构模式：MVVM + Repository                 │
└─────────────────────────────────────────────┘

2.2 技术选型理由

为什么选择 ArkTS 而不是 TypeScript？

ArkTS 是华为在 TypeScript 基础上为 HarmonyOS 量身定制的编程语言。相比原生 TypeScript，ArkTS 具备以下优势：

  1. 静态类型增强：禁用 any、unknown，强制显式类型声明
  2. 运行时性能：通过 AOT 编译获得接近原生的执行效率
  3. ArkUI 原生支持：内置 @Component、@State 等装饰器
  4. 企业级约束：严格的语言规范降低代码缺陷率

参考 ArkTS 语言规范 了解更多语法限制。

为什么选择 MVVM + Repository 架构？

// MVVM 架构分层示例
// View 层：负责 UI 渲染
@Component
export struct HomeView {
  @State viewModel: HomeViewModel = new HomeViewModel()
  
  build() {
    Column() {
      Text(this.viewModel.todayExpense)
    }
  }
}

// ViewModel 层：负责业务逻辑
export class HomeViewModel {
  todayExpense: string = '0.00'
  
  async loadTodayData(): Promise<void> {
    const bills = await BillRepository.getTodayBills()
    this.todayExpense = MoneyUtil.format(bills.sum())
  }
}

// Repository 层：负责数据访问
export class BillRepository {
  static async getTodayBills(): Promise<Bill[]> {
    return await PersistenceV2.query(Bill, 'date = today')
  }
}

这种架构带来三大核心优势：

  • 解耦：UI、业务、数据三层完全分离
  • 可测试：ViewModel 可独立单元测试
  • 可替换：Repository 层屏蔽底层存储实现

三、项目架构设计

3.1 整体架构图

HarmonyLedger 采用经典的 MVVM + Repository 分层架构，数据流向为单向流动：

┌──────────────────────────────────────────────────────┐
│                    UI 层 (View)                      │
│  pages/  components/  router/                        │
│  ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐      │
│  │Splash│ │ Home │ │ Add  │ │ Stats│ │Budget│      │
│  └──────┘ └──────┘ └──────┘ └──────┘ └──────┘      │
└────────────────────┬─────────────────────────────────┘
                     │ 数据绑定 (@State/@Link)
┌────────────────────▼─────────────────────────────────┐
│               ViewModel 层 (业务逻辑)                │
│  viewmodel/                                          │
│  ┌────────────┐ ┌────────────┐ ┌────────────┐       │
│  │HomeVM      │ │AddBillVM   │ │StatsVM     │       │
│  └────────────┘ └────────────┘ └────────────┘       │
└────────────────────┬─────────────────────────────────┘
                     │ 方法调用
┌────────────────────▼─────────────────────────────────┐
│             Repository 层 (数据访问)                 │
│  repository/                                         │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐            │
│  │BillRepo  │ │CatRepo   │ │BudgetRepo│            │
│  └──────────┘ └──────────┘ └──────────┘            │
└────────────────────┬─────────────────────────────────┘
                     │ ORM 操作
┌────────────────────▼─────────────────────────────────┐
│           PersistenceV2 / Preferences                │
│           Local Database / KV Store                  │
└──────────────────────────────────────────────────────┘

3.2 架构分层职责

分层 目录 职责
UI 层 pages/ components/ 界面渲染、用户交互、路由跳转
ViewModel 层 viewmodel/ 业务逻辑处理、状态管理、数据转换
Repository 层 repository/ 数据访问抽象、缓存策略、数据源切换
Model 层 model/ 数据实体定义、领域模型
Service 层 service/ 公共业务服务（通知、导出等）
Utils 层 utils/ 工具类（日期、金额、日志等）

架构约束：禁止 UI 层直接访问 Repository，必须通过 ViewModel 中转。这是保证代码可测试性的关键。

四、页面规划详解

4.1 页面清单

HarmonyLedger 共规划 12 个核心页面，覆盖记账应用的全部业务场景：

{
  "pages": [
    { "name": "Splash",    "path": "pages/Splash",    "desc": "启动页" },
    { "name": "Home",      "path": "pages/Home",      "desc": "首页" },
    { "name": "AddBill",   "path": "pages/AddBill",   "desc": "新增账单" },
    { "name": "EditBill",  "path": "pages/EditBill",  "desc": "编辑账单" },
    { "name": "BillDetail","path": "pages/BillDetail","desc": "账单详情" },
    { "name": "Statistics","path": "pages/Statistics","desc": "统计分析" },
    { "name": "Budget",    "path": "pages/Budget",    "desc": "预算中心" },
    { "name": "Category",  "path": "pages/Category",  "desc": "分类管理" },
    { "name": "Search",    "path": "pages/Search",    "desc": "搜索" },
    { "name": "Setting",   "path": "pages/Setting",   "desc": "设置" },
    { "name": "About",     "path": "pages/About",     "desc": "关于" }
  ]
}

4.2 核心页面功能

首页 (Home) 是用户进入应用后的主界面，需要一目了然地展示当日财务概况：

  1. 今日支出汇总卡片
  2. 今日收入汇总卡片
  3. 最近账单列表（最多 10 条）
  4. 快捷新增按钮（FAB）
  5. 底部 Tab 导航

新增账单 (AddBill) 是用户最频繁操作的页面，设计要求极简高效：

  1. 收入/支出类型切换
  2. 金额输入（MoneyInput 组件）
  3. 分类选择（CategorySelector 组件）
  4. 日期选择（DateSelector 组件）
  5. 备注输入
  6. 图片附件（可选）
  7. 保存按钮

用户体验原则：新增账单页面从打开到保存完成，操作步数不超过 5 步。

五、数据模型设计

5.1 核心数据模型

HarmonyLedger 共设计 4 个核心数据模型，覆盖记账应用全部业务场景：

// model/Bill.ets - 账单实体
@Entity('bill')
export class Bill {
  @PrimaryKey()
  id: string = UUIDUtil.generate()
  
  @Column()
  money: number = 0          // 金额（分）
  
  @Column()
  type: BillType = BillType.EXPENSE  // 收入/支出
  
  @Column()
  categoryId: string = ''    // 分类ID
  
  @Column()
  remark: string = ''        // 备注
  
  @Column()
  date: number = Date.now()  // 账单日期
  
  @Column()
  createTime: number = Date.now()
  
  @Column()
  updateTime: number = Date.now()
}

5.2 数据模型关系图

模型 字段数 用途 关联
Bill 8 账单记录 categoryId → Category
Category 6 收支分类 独立
Budget 5 预算记录 独立（按月份）
Setting 5 应用设置 独立（单例） 
┌───────────┐         ┌────────────┐
│   Bill    │ N : 1   │  Category  │
│───────────│────────▶│────────────│
│ id        │         │ id         │
│ money     │         │ name       │
│ type      │         │ icon       │
│ categoryId│         │ color      │
│ date      │         │ sort       │
└───────────┘         └────────────┘

设计要点：金额字段 money 以"分"为单位存储，避免浮点数精度问题。这是金融类应用的基本规范。

六、公共组件规划

6.1 组件库清单

HarmonyLedger 规划了 23 个高复用公共组件，覆盖 UI 层全部需求：

// components/ 目录结构示例
components/
├── bill/
│   ├── BillCard.ets           # 账单卡片
│   └── SummaryCard.ets        # 汇总卡片
├── input/
│   ├── MoneyInput.ets         # 金额输入
│   ├── SearchBar.ets          # 搜索栏
│   └── AppButton.ets          # 通用按钮
├── chart/
│   ├── CircleChart.ets        # 饼图
│   ├── BarChart.ets           # 柱状图
│   └── LineChart.ets          # 折线图
├── selector/
│   ├── CategorySelector.ets   # 分类选择器
│   ├── DateSelector.ets       # 日期选择器
│   └── MonthSelector.ets      # 月份选择器
├── common/
│   ├── LoadingView.ets        # 加载视图
│   ├── EmptyView.ets          # 空视图
│   └── AppDialog.ets          # 通用对话框
└── navigation/
    ├── AppNavigationBar.ets   # 导航栏
    └── AppTabBar.ets          # 底部Tab

6.2 组件设计规范

所有公共组件必须遵循以下设计规范：

  1. 单一职责：每个组件只负责一个明确的 UI 功能
  2. 参数化：通过 @Prop / @Link 暴露可配置项
  3. 事件回调：通过 @BuilderParam 暴露事件接口
  4. 样式独立：组件样式通过 theme/ 统一管理
  5. 行数限制：单个组件 100-200 行，超出则拆分

参考 ArkUI 组件最佳实践 了解组件化开发规范。

七、工具类设计

7.1 工具类清单

HarmonyLedger 封装了 11 个企业级工具类，提供通用能力支撑：

工具类 文件 用途
DateUtil utils/DateUtil.ets 日期格式化、计算
MoneyUtil utils/MoneyUtil.ets 金额格式化、转换
RouterUtil utils/RouterUtil.ets 路由跳转封装
PreferenceUtil utils/PreferenceUtil.ets Preferences 封装
ThemeUtil utils/ThemeUtil.ets 主题切换管理
ToastUtil utils/ToastUtil.ets Toast 提示封装
DialogUtil utils/DialogUtil.ets 对话框封装
PermissionUtil utils/PermissionUtil.ets 权限申请封装
StringUtil utils/StringUtil.ets 字符串处理
LogUtil utils/LogUtil.ets 日志工具
UUIDUtil utils/UUIDUtil.ets UUID 生成

7.2 工具类示例

// utils/MoneyUtil.ets - 金额工具类
export class MoneyUtil {
  /**
   * 分转元字符串
   * @param cents 金额（分）
   * @returns 格式化后的金额字符串，如 "123.45"
   */
  static format(cents: number): string {
    const yuan = cents / 100
    return yuan.toFixed(2)
  }
  
  /**
   * 元转分
   * @param yuan 金额（元）
   * @returns 金额（分）
   */
  static toCents(yuan: number): number {
    return Math.round(yuan * 100)
  }
  
  /**
   * 金额千分位格式化
   * @param cents 金额（分）
   * @returns 带千分位的金额字符串，如 "1,234.56"
   */
  static formatWithComma(cents: number): string {
    const yuan = this.format(cents)
    const parts = yuan.split('.')
    parts[0] = parts[0].replace(/\B(?=(\d{3})+(?!\d))/g, ',')
    return parts.join('.')
  }
}

八、主题规范

8.1 设计风格

HarmonyLedger 采用 现代简洁 的设计风格，融合苹果风与 MIUI 风格的视觉特点：

  • 圆角设计：统一 16dp 圆角，营造柔和视觉
  • 卡片布局：信息以卡片形式承载，层次清晰
  • 留白处理：20dp Padding，保证视觉呼吸感
  • 色彩语义：收入绿色、支出红色、预算蓝色、统计紫色

8.2 主题色定义

// theme/Colors.ets - 主题色定义
export class AppColors {
  // 收入 - 绿色系
  static readonly Income: string = '#34C759'
  static readonly IncomeLight: string = '#E8F8EE'
  
  // 支出 - 红色系
  static readonly Expense: string = '#FF3B30'
  static readonly ExpenseLight: string = '#FFEBE9'
  
  // 预算 - 蓝色系
  static readonly Budget: string = '#007AFF'
  static readonly BudgetLight: string = '#E3F0FF'
  
  // 统计 - 紫色系
  static readonly Statistic: string = '#AF52DE'
  static readonly StatisticLight: string = '#F5E8FB'
  
  // 中性色
  static readonly Background: string = '#F2F2F7'
  static readonly CardBackground: string = '#FFFFFF'
  static readonly PrimaryText: string = '#1C1C1E'
  static readonly SecondaryText: string = '#8E8E93'
}
色彩用途 主色 浅色 应用场景
收入 #34C759 #E8F8EE 收入账单卡片
支出 #FF3B30 #FFEBE9 支出账单卡片
预算 #007AFF #E3F0FF 预算进度条
统计 #AF52DE #F5E8FB 图表图例

深色模式支持：所有颜色通过 theme/ 模块统一管理，支持深浅模式自动切换。详见第 23 篇博客。

九、Git 版本规划

9.1 版本号策略

HarmonyLedger 采用 语义化版本号 策略，30 个 Git Tag 分三个阶段：

阶段一：基础架构 (v0.0.1 ~ v0.0.5)
├── v0.0.1 创建工程
├── v0.0.2 项目目录
├── v0.0.3 主题系统
├── v0.0.4 底部导航
└── v0.0.5 首页

阶段二：核心功能 (v0.0.6 ~ v0.2.5)
├── v0.0.6 BillCard
├── v0.0.7 Repository
├── ...
└── v0.2.5 数据导出

阶段三：优化发布 (v0.2.6 ~ v1.0.0)
├── v0.2.6 组件重构
├── v0.2.7 性能优化
├── ...
└── v1.0.0 正式版

9.2 Git Commit 规范

所有 Commit Message 必须遵循 Conventional Commits 规范：

# 功能新增
feat(home): 完成首页布局与 SummaryCard 设计

# Bug 修复
fix(search): 修复搜索结果分页错误

# 重构
refactor(repository): 抽象 BaseRepository 通用接口

# 文档
docs(article-08): 新增第8篇博客《新增账单页面开发》

# 样式
style(theme): 调整深色模式卡片背景色

# 性能优化
perf(statistics): 优化饼图绘制性能，减少 30% 渲染时间
Commit 类型 用途 示例
feat 新功能 feat(bill): 新增账单功能
fix Bug 修复 fix(search): 修复搜索崩溃
refactor 重构 refactor(repository): 重构数据访问层
docs 文档 docs(readme): 更新 README
style 样式 style(theme): 调整主题色
perf 性能 perf(chart): 优化图表渲染
test 测试 test(utils): 新增 MoneyUtil 测试
chore 构建/工具 chore(build): 更新构建脚本

参考 Conventional Commits 规范 了解更多。

十、30 篇博客规划

10.1 博客系列总览

本系列共 30 篇博客，每篇对应一个 Git Tag，覆盖从工程创建到正式发布的完整生命周期：

序号 博客标题 Git Tag
01 HarmonyOS NEXT 企业级记账APP：项目规划与效果展示 v0.0.1
02 创建工程与企业级目录结构设计 v0.0.2
03 搭建全局主题与 Design Token v0.0.3
04 实现底部 Tab 导航 v0.0.4
05 首页布局与 SummaryCard 设计 v0.0.5
06 封装 BillCard 通用组件 v0.0.6
07 设计 Repository 与数据模型 v0.0.7
08 新增账单页面开发 v0.0.8
09 封装金额输入组件 MoneyInput v0.0.9
10 分类选择器开发 v0.1.0
11 日期与时间选择组件 v0.1.1
12 Preferences 数据持久化 v0.1.2
13 PersistenceV2 数据库升级 v0.1.3
14 账单编辑与删除 v0.1.4
15 账单搜索与筛选 v0.1.5
16 预算中心开发 v0.1.6
17 预算提醒与预算进度 v0.1.7
18 统计分析首页 v0.1.8
19 Canvas 绘制饼图 v0.1.9
20 Canvas 绘制柱状图 v0.2.0
21 Canvas 绘制折线图 v0.2.1
22 分类管理模块 v0.2.2
23 深色模式与主题切换 v0.2.3
24 设置中心开发 v0.2.4
25 数据导出、备份与恢复 v0.2.5
26 公共组件与工具类重构 v0.2.6
27 项目性能优化 v0.2.7
28 打包发布与签名配置 v0.2.8
29 源码解析与项目复盘 v0.2.9
30 企业级项目总结与后续规划 v1.0.0

10.2 博客质量规范

每篇博客严格遵循 CSDN 高分文章规范（目标 98-100 分）：

  1. 篇幅：400-500 行，深度技术解析
  2. 代码：8 个以上代码块，标注语言类型
  3. 图表：3 个以上表格，1 张以上图片
  4. 结构：10 个以上二级标题，8 个以上三级标题
  5. 元素：有序列表、无序列表、引用块、加粗文字全覆盖
  6. 链接：8 个以上有效外部链接

可独立学习：每篇博客配套完整源码、Git Tag、运行截图，读者可单独学习某一篇而不依赖前序内容。

十一、项目目录结构

11.1 完整目录树

HarmonyLedger 工程目录严格遵循企业级项目规范，整个开发周期保持目录结构稳定：

HarmonyLedger/
├── AppScope/                    # 应用级配置
│   ├── app.json5
│   └── resources/
├── entry/                       # 主模块
│   ├── src/main/
│   │   ├── ets/
│   │   │   ├── pages/           # 页面
│   │   │   ├── components/      # 公共组件
│   │   │   ├── viewmodel/       # 视图模型
│   │   │   ├── repository/      # 数据访问层
│   │   │   ├── model/           # 数据模型
│   │   │   ├── service/         # 业务服务
│   │   │   ├── database/        # 数据库
│   │   │   ├── router/          # 路由
│   │   │   ├── utils/           # 工具类
│   │   │   ├── theme/           # 主题
│   │   │   ├── constants/       # 常量
│   │   │   └── common/          # 公共能力
│   │   └── resources/
│   ├── build-profile.json5
│   └── oh-package.json5
├── docs/                        # 文档
│   └── articles/                # 30篇博客
├── deveco-skills/               # DevEco 开发技能包
├── README.md
├── CHANGELOG.md
└── .gitignore

11.2 目录设计原则

  1. 分层清晰：MVVM 各层目录独立，职责明确
  2. 按功能聚合：同类文件聚合在同一目录（如 chart/ 下所有图表组件）
  3. 避免过深嵌套：目录层级控制在 4 层以内
  4. 预留扩展空间：common/、constants/ 等目录为后续扩展预留

禁止后期随意修改目录结构。如需调整，必须通过正式的架构评审。

十二、AI 生成要求

12.1 AI 角色定位

AI（Trae / Codex / Claude Code / ChatGPT）在本项目中担任 首席架构师和核心开发工程师，需全程遵循以下规则：

  1. 严格按照产品设计文档执行，不得擅自改变整体方案
  2. 所有代码兼容最新 HarmonyOS NEXT 和 DevEco Studio，可直接编译运行
  3. 每完成一个阶段，保证项目处于可运行状态
  4. 遵循统一的命名规范、注释规范、目录规范和 Git Commit 规范
  5. 优先考虑代码可维护性、可扩展性和企业级实践
  6. 所有页面、组件、工具类具备复用能力，避免重复代码

12.2 每次开发输出清单

每完成一个功能模块，必须同步输出以下 8 类交付物：

### 一、需求分析
- 功能介绍
- 业务流程
- 设计思路

### 二、页面结构
- 页面树
- 组件树

### 三、ArkTS 源码
- 完整源码，不能省略

### 四、代码讲解
- 逐段解释关键逻辑

### 五、最佳实践
- 为什么这么设计
- 还有哪些优化方案

### 六、Git
- Commit Message
- Git Tag
- CHANGELOG 更新

### 七、博客
- 适合 CSDN/掘金/知乎/公众号的高质量博客

### 八、截图说明
- 当前页面需要截图哪些内容

十三、开发环境与运行方式

13.1 开发环境要求

环境项 版本要求 说明
DevEco Studio 5.0+ 官方 IDE
HarmonyOS SDK 5.0+ (API 12+) 目标 SDK
Node.js 18+ 构建工具链
OHOS NDK 随 SDK 原生编译
Git 2.30+ 版本控制

13.2 本地运行步骤

# 1. 克隆仓库
git clone https://gitcode.com/qiaomu8559968/HarmonyLedger.git.git
cd HarmonyLedger

# 2. 切换到目标版本
git checkout v1.0.0

# 3. 安装依赖
ohpm install

# 4. DevEco Studio 打开项目
# File → Open → 选择 HarmonyLedger 目录

# 5. 连接鸿蒙真机或启动模拟器
hdc list targets

# 6. 编译运行
# DevEco Studio 工具栏点击 Run 按钮

首次运行提示：如遇 SDK 版本不匹配，请在 DevEco Studio 的 File → Project Structure → Project 中切换 SDK 版本。

附录：运行效果截图

在这里插入图片描述

总结

本文作为 HarmonyLedger 系列的开篇，完整介绍了项目的 定位、技术栈、架构设计、页面规划、数据模型、组件库、工具类、主题规范、Git 版本规划以及 30 篇博客的总览。

通过本文，你可以清晰地了解：

  • HarmonyLedger 是一款 企业级 鸿蒙记账 APP，非 Demo 项目
  • 采用 MVVM + Repository 架构，三层解耦
  • 规划 12 个页面、23 个组件、11 个工具类、4 个数据模型
  • 通过 30 个 Git Tag 循序渐进构建完整应用
  • 配套 30 篇高质量博客，每篇可独立学习

下一篇预告：《创建工程与企业级目录结构设计》将手把手带你使用 DevEco Studio 创建 HarmonyLedger 工程骨架，并搭建符合企业级规范的目录结构与基础配置文件。

如果这篇文章对你有帮助，欢迎点赞👍、收藏⭐、关注🔔，你的支持是我持续创作的动力！

相关资源

# harmonyos # 华为
Logo
人工智能6S服务平台

作为“人工智能6S店”的官方数字引擎，为AI开发者与企业提供一个覆盖软硬件全栈、一站式门户。

更多推荐

cover

错题分析模板：基于鸿蒙HarmonyOS NEXT与鸿蒙PC的智能学习辅助应用技术实现

avatar 人工智能6S服务平台
cover

演讲稿生成器：基于鸿蒙HarmonyOS NEXT与鸿蒙PC的智能演讲辅助应用技术实现

avatar 人工智能6S服务平台
cover

考试复习规划：基于鸿蒙HarmonyOS NEXT的智能学习规划应用技术实现深度解析

avatar 人工智能6S服务平台