# WalletWise
**Repository Path**: Agions/walletwise
## Basic Information
- **Project Name**: WalletWise
- **Description**: WalletWise 是一款基于鸿蒙 HarmonyOS NEXT 的智能财务管理应用，采用 ArkTS 语言和 ArkUI 框架开发。它帮助用户轻松管理个人财务，追踪收支情况，分析消费习惯，设定预算目标
- **Primary Language**: Shell
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No
## Statistics
- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-03-25
- **Last Updated**: 2026-05-29
## Categories & Tags
**Categories**: Uncategorized
**Tags**: None
## README
# 💰 WalletWise
### 智慧钱包 · 鸿蒙版
[](LICENSE)
[](https://developer.harmonyos.com/)
[](https://developer.harmonyos.com/cn/docs/documentation/arkts-apis-overview-0000001518082977)
[](https://gitee.com/Agions/walletwise/releases)
**一款优雅、高效的个人财务管理应用**
**让每一笔收支都清晰可见，让每一个预算都心中有数**
[功能特性](#-功能特性) · [快速开始](#-快速开始) · [架构设计](#-架构设计) · [开发指南](#-开发指南) · [版本对比](#-版本对比)
---
## 📖 项目简介
**WalletWise** 是一款基于鸿蒙 HarmonyOS NEXT 的智能财务管理应用，采用 ArkTS 语言和 ArkUI 框架开发。它帮助用户轻松管理个人财务，追踪收支情况，分析消费习惯，设定预算目标。
> 🎯 **设计理念**：简洁、高效、离线优先
---
## ✨ 功能特性
|
### 💳 智能记账
- 快速记录日常收支
- 支持分类、备注、日期
- 批量导入导出
- 智能分类推荐
|
### 📊 数据分析
- 多维度统计图表
- 消费趋势分析
- 分类支出占比
- 月度/年度对比
|
|
### 🎯 预算管理
- 月度/分类预算
- 实时预算监控
- 超支预警提醒
- 预算完成度追踪
|
### 🏷️ 分类管理
- 自定义收支分类
- 图标自由选择
- 分类排序调整
- 默认分类模板
|
|
### 🌙 深色模式
- 完整深色主题
- 跟随系统切换
- 护眼配色方案
- 平滑过渡动画
|
### 📱 离线优先
- 本地 SQLite 存储
- 无需网络运行
- 数据安全可靠
- 隐私完全掌控
|
---
## 🚀 快速开始
### 环境要求
| 工具 | 版本要求 | 说明 |
|------|----------|------|
| DevEco Studio | 4.0+ | 华为官方 IDE |
| HarmonyOS SDK | API 9+ | 鸿蒙开发套件 |
| Node.js | 16+ | 构建工具依赖 |
### 安装步骤
```bash
# 1. 克隆项目
git clone git@gitee.com:Agions/walletwise.git
# 2. 使用 DevEco Studio 打开项目
# File -> Open -> 选择 walletwise 目录
# 3. 等待依赖安装完成
# 4. 连接设备或启动模拟器
# 5. 点击 Run 运行应用
```
### 首次运行
应用首次启动时会自动：
1. ✅ 初始化本地数据库
2. ✅ 创建默认分类（10个支出 + 5个收入）
3. ✅ 设置默认用户偏好
---
## 🏗️ 架构设计
### 分层架构
```
┌─────────────────────────────────────────────────────────────┐
│ UI 层 (Pages) │
│ 页面布局与用户交互 │
├─────────────────────────────────────────────────────────────┤
│ State 层 (Stores) │
│ 全局状态管理 (AppStorage) │
├─────────────────────────────────────────────────────────────┤
│ Repository 层 (数据仓库) │
│ 统一数据源入口 │
├─────────────────────────────────────────────────────────────┤
│ Service 层 (Database) │
│ 底层数据库操作 │
└─────────────────────────────────────────────────────────────┘
```
### 目录结构
```
WalletWise/
├── AppScope/ # 应用级配置
│ └── app.json5 # 应用元数据
├── src/
│ └── main/
│ ├── ets/
│ │ ├── components/ # 🧩 通用 UI 组件
│ │ │ ├── HeaderCard.ets # 首页顶部卡片
│ │ │ ├── TransactionItem.ets# 交易列表项
│ │ │ ├── BudgetItem.ets # 预算列表项
│ │ │ └── CategoryItem.ets # 分类网格项
│ │ │
│ │ ├── common/ # 📦 公共模块
│ │ │ ├── Styles.ets # 全局样式常量
│ │ │ ├── constants/ # 常量定义
│ │ │ ├── errors/ # 错误处理
│ │ │ ├── models/ # 数据模型
│ │ │ └── services/ # 数据服务
│ │ │
│ │ ├── pages/ # 📄 页面组件
│ │ │ ├── Index.ets # 主入口
│ │ │ ├── HomePage.ets # 首页
│ │ │ ├── StatisticsPage.ets # 统计页
│ │ │ ├── BudgetPage.ets # 预算页
│ │ │ ├── CategoryPage.ets # 分类页
│ │ │ ├── MinePage.ets # 个人中心
│ │ │ └── SettingsPage.ets # 设置页
│ │ │
│ │ ├── repository/ # 🗄️ 数据仓库层
│ │ │ ├── TransactionRepository.ets
│ │ │ ├── CategoryRepository.ets
│ │ │ ├── BudgetRepository.ets
│ │ │ └── UserSettingsRepository.ets
│ │ │
│ │ ├── services/ # ⚙️ 服务层
│ │ │ └── database/
│ │ │ └── DatabaseHelper.ets
│ │ │
│ │ ├── stores/ # 📊 状态管理
│ │ │ ├── ThemeStore.ets # 主题状态
│ │ │ └── UserStore.ets # 用户状态
│ │ │
│ │ └── utils/ # 🔧 工具类
│ │ ├── DateUtils.ets # 日期工具
│ │ ├── CurrencyUtils.ets # 货币工具
│ │ ├── StringUtils.ets # 字符串工具
│ │ └── IconUtils.ets # 图标工具
│ │
│ └── resources/ # 📁 资源文件
│ ├── base/
│ └── rawfile/icons/ # 图标资源
└── hvigorfile.ts # 构建配置
```
---
## 📊 数据库设计
### ER 图
```
┌──────────────────┐ ┌──────────────────┐
│ transactions │ │ categories │
├──────────────────┤ ├──────────────────┤
│ id (PK) │ │ id (PK) │
│ amount │ │ name │
│ type │◄──────│ icon │
│ category_id (FK) │ │ type │
│ date │ │ sort_order │
│ note │ │ is_default │
│ created_at │ │ created_at │
│ updated_at │ └──────────────────┘
└──────────────────┘
┌──────────────────┐ ┌──────────────────┐
│ budgets │ │ user_settings │
├──────────────────┤ ├──────────────────┤
│ id (PK) │ │ key (PK) │
│ category_id (FK) │ │ value │
│ amount │ │ updated_at │
│ month │ └──────────────────┘
│ created_at │
│ updated_at │
└──────────────────┘
```
### 表结构说明
| 表名 | 说明 | 主要字段 |
|------|------|----------|
| `transactions` | 收支记录 | id, amount, type, category_id, date, note |
| `categories` | 自定义分类 | id, name, icon, type, sort_order |
| `budgets` | 预算设定 | id, category_id, amount, month |
| `user_settings` | 用户偏好 | key, value |
---
## 🛠️ 开发指南
### 代码规范
| 类型 | 规范 | 示例 |
|------|------|------|
| 文件名 | PascalCase | `TransactionListPage.ets` |
| 目录名 | snake_case | `pages/transaction/` |
| 类/接口 | PascalCase | `class DataService {}` |
| 变量/函数 | camelCase | `const userName = ''` |
| 常量 | UPPER_SNAKE_CASE | `const MAX_AMOUNT = 999999` |
### 工具类一览
| 工具类 | 用途 | 常用方法 |
|--------|------|----------|
| `DateUtils` | 日期处理 | `formatDate()`, `getMonthStartDate()` |
| `CurrencyUtils` | 货币格式化 | `formatAmount()`, `formatCompactAmount()` |
| `StringUtils` | 字符串处理 | `truncate()`, `isEmpty()`, `maskSensitiveInfo()` |
| `IconUtils` | 图标管理 | `getIconPath()`, `getCategoryIconPath()` |
### 错误处理
```typescript
import { AppError, ErrorHandler } from '../common/errors/AppError';
try {
await dataService.addTransaction(transaction);
} catch (error) {
const message = ErrorHandler.handle(error, '添加交易记录');
promptAction.showToast({ message });
}
```
---
## 📊 项目数据
| 指标 | 数值 |
|------|------|
| **代码行数** | 3,600+ 行 |
| **文件数量** | 33 个 |
| **组件数量** | 4 个通用组件 |
| **页面数量** | 7 个 |
| **数据库表** | 4 张 |
| **工具类** | 4 个 |
---
## 📈 性能优化
### 已实现的优化
- ✅ **智能缓存**：5 分钟缓存过期机制
- ✅ **O(1) 查询**：分类 Map 缓存，快速查找
- ✅ **批量操作**：支持批量添加交易记录
- ✅ **懒加载**：按需加载数据，减少启动时间
- ✅ **内存优化**：合理使用缓存，避免内存泄漏
### 性能指标
| 指标 | 目标值 | 说明 |
|------|--------|------|
| 启动时间 | < 1s | 冷启动到首页可交互 |
| 页面切换 | < 300ms | Tab 切换响应时间 |
| 数据加载 | < 500ms | 首页数据加载完成 |
| 内存占用 | < 100MB | 正常使用内存峰值 |
---
## 🤝 贡献指南
我们欢迎所有形式的贡献！
### 如何贡献
1. **Fork** 本仓库
2. 创建特性分支：`git checkout -b feature/amazing-feature`
3. 提交更改：`git commit -m 'feat: add amazing feature'`
4. 推送分支：`git push origin feature/amazing-feature`
5. 创建 **Pull Request**
### Commit 规范
```
():
类型：
- feat: 新功能
- fix: 修复 Bug
- docs: 文档更新
- style: 代码格式调整
- refactor: 代码重构
- perf: 性能优化
- test: 测试相关
- chore: 构建/工具相关
```
### 开发流程
```bash
# 1. 克隆并进入项目
git clone git@gitee.com:Agions/walletwise.git
cd walletwise
# 2. 创建特性分支
git checkout -b feature/your-feature
# 3. 开发并测试
# ... 编写代码 ...
# 4. 提交更改
git add .
git commit -m "feat: your feature description"
# 5. 推送并创建 PR
git push origin feature/your-feature
```
---
## 📄 许可证
本项目采用 [MIT License](LICENSE) 开源许可证。
```
MIT License
Copyright (c) 2024-2026 Agions
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
```
---
## 🔗 相关链接
- 📚 [HarmonyOS 开发文档](https://developer.harmonyos.com/)
- 🛠️ [DevEco Studio 下载](https://developer.harmonyos.com/cn/develop/deveco-studio)
- 📖 [ArkTS 语言指南](https://developer.harmonyos.com/cn/docs/documentation/arkts-guides/overview-0000001518082977)
---
## 👨💻 开发者
**Agions**
- GitHub: [@Agions](https://github.com/Agions)
- Gitee: [@Agions](https://gitee.com/Agions)
---
### 🌟 如果这个项目对你有帮助，请给一个 Star 支持一下！
**Made with ❤️ for HarmonyOS**