# LedgerWise

**Repository Path**: Agions/LedgerWise

## Basic Information

- **Project Name**: LedgerWise
- **Description**: 智慧记账 - 专业级个人财务管理应用 | Vue 3 + TypeScript + uni-app + Pinia
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-03-17
- **Last Updated**: 2026-05-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: vue3, TypeScript, uni-app, vite, accounting

## README

<div align="center">

# 🏦 LedgerWise

**智慧记账 · 专业级个人财务管理应用**

[![Vue 3](https://img.shields.io/badge/Vue-3.4-42b883?style=flat-square&logo=vue.js)](https://vuejs.org/)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.3-3178c6?style=flat-square&logo=typescript)](https://www.typescriptlang.org/)
[![uni-app](https://img.shields.io/badge/uni--app-3.x-2b9939?style=flat-square)](https://uniapp.dcloud.net.cn/)
[![Pinia](https://img.shields.io/badge/Pinia-2.x-f8c926?style=flat-square)](https://pinia.vuejs.org/)
[![License](https://img.shields.io/badge/License-MIT-blue?style=flat-square)](LICENSE)

*简洁高效的跨平台记账应用，轻松管理个人财务、跟踪收支、分析消费习惯并实现预算目标*

[功能特性](#-功能特性) · [快速开始](#-快速开始) · [项目架构](#-项目架构) · [技术栈](#-技术栈) · [开发指南](#-开发指南)

</div>

---

## ✨ 功能特性

### 💰 智能记账
- **快速记录** - 3秒完成一笔记账，支持收入/支出切换
- **分类管理** - 25+预设分类，支持自定义图标和颜色
- **多维备注** - 支持文字备注，方便追溯每笔消费

### 📊 数据分析
- **可视化图表** - 饼图展示分类占比，柱状图展示趋势
- **多维度统计** - 按日/周/月/年查看收支情况
- **消费洞察** - 智能分析消费习惯，发现节省空间

### 🎯 预算管理
- **月度预算** - 设置月度总预算，实时追踪使用情况
- **分类预算** - 为不同分类设置独立预算限额
- **超支预警** - 预算使用超过阈值自动提醒

### 👤 个人中心
- **数据导出** - 支持导出账单数据
- **缓存管理** - 一键清理缓存，保持应用流畅
- **多端适配** - 支持 H5、微信小程序、App 等多端运行

---

## 🚀 快速开始

### 环境要求

- **Node.js** >= 18.0.0
- **npm** >= 9.0.0 或 **yarn** >= 1.22.0
- **HBuilderX** (推荐，用于 uni-app 开发)

### 安装与运行

```bash
# 1. 克隆项目
git clone https://gitee.com/Agions/LedgerWise.git
cd LedgerWise

# 2. 安装依赖
npm install

# 3. 启动开发服务器 (H5)
npm run dev:h5

# 4. 启动微信小程序
npm run dev:mp-weixin

# 5. 构建生产版本
npm run build:h5
npm run build:mp-weixin
```

### 使用 HBuilderX

1. 下载并安装 [HBuilderX](https://www.dcloud.io/hbuilderx.html)
2. 导入项目文件夹
3. 点击运行 → 运行到浏览器/模拟器/小程序

---

## 🏗️ 项目架构

```
LedgerWise/
├── src/
│   ├── pages/                    # 📄 页面组件
│   │   ├── index/               #    首页 - 收支概览
│   │   ├── record/              #    记账 - 添加/列表
│   │   ├── statistics/          #    统计 - 数据分析
│   │   ├── budget/              #    预算 - 管理设置
│   │   ├── category/            #    分类 - 自定义管理
│   │   ├── profile/             #    个人中心
│   │   └── login/               #    登录页
│   │
│   ├── components/              # 🧩 公共组件
│   │   ├── bill-card/           #    账单卡片
│   │   ├── chart/               #    图表组件
│   │   ├── category-picker/     #    分类选择器
│   │   └── amount-input/        #    金额输入
│   │
│   ├── composables/             # 🔧 组合式函数 (Vue 3 核心)
│   │   ├── useBill.ts           #    账单逻辑
│   │   ├── useBudget.ts         #    预算逻辑
│   │   ├── useCategory.ts       #    分类逻辑
│   │   ├── useChart.ts          #    图表逻辑
│   │   └── useAuth.ts           #    认证逻辑
│   │
│   ├── store/                   # 📦 Pinia 状态管理
│   │   ├── index.ts             #    Store 入口
│   │   ├── user.ts              #    用户状态
│   │   ├── bill.ts              #    账单状态
│   │   ├── category.ts          #    分类状态
│   │   └── budget.ts            #    预算状态
│   │
│   ├── services/                # 🌐 API 服务层
│   │   ├── request.ts           #    请求封装
│   │   ├── auth.ts              #    认证服务
│   │   ├── bill.ts              #    账单服务
│   │   ├── category.ts          #    分类服务
│   │   └── budget.ts            #    预算服务
│   │
│   ├── types/                   # 📝 TypeScript 类型
│   │   ├── index.ts             #    类型入口
│   │   ├── bill.ts              #    账单类型
│   │   ├── category.ts          #    分类类型
│   │   └── user.ts              #    用户类型
│   │
│   ├── utils/                   # 🛠️ 工具函数
│   │   ├── date.ts              #    日期处理
│   │   ├── currency.ts          #    货币格式化
│   │   ├── storage.ts           #    本地存储
│   │   └── validation.ts        #    数据验证
│   │
│   ├── config/                  # ⚙️ 配置文件
│   │   ├── constants.ts         #    常量定义
│   │   └── categories.ts        #    默认分类
│   │
│   ├── assets/                  # 🎨 静态资源
│   │   ├── icons/               #    图标
│   │   ├── images/              #    图片
│   │   └── styles/              #    样式文件
│   │       ├── variables.scss   #    SCSS 变量
│   │       ├── mixins.scss      #    混入
│   │       └── common.scss      #    公共样式
│   │
│   ├── App.vue                  #    根组件
│   ├── main.ts                  #    入口文件
│   ├── pages.json               #    页面配置
│   ├── manifest.json            #    应用配置
│   └── env.d.ts                 #    类型声明
│
├── public/                      # 📁 公共资源
├── package.json                 #    项目配置
├── tsconfig.json                #    TypeScript 配置
├── vite.config.ts               #    Vite 配置
└── README.md                    #    项目说明
```

---

## 🛠️ 技术栈

| 分类 | 技术 | 版本 | 说明 |
|------|------|------|------|
| **核心框架** | Vue 3 | 3.4+ | 渐进式 JavaScript 框架 |
| **跨平台方案** | uni-app | 3.x | 一套代码，多端运行 |
| **类型系统** | TypeScript | 5.3+ | 类型安全，智能提示 |
| **状态管理** | Pinia | 2.x | Vue 3 官方推荐状态管理 |
| **图表库** | uCharts | 2.5+ | 专为 uni-app 设计的图表 |
| **构建工具** | Vite | 5.x | 下一代前端构建工具 |
| **CSS 预处理** | Sass | 1.70+ | CSS 扩展语言 |

### 架构特点

- ✅ **Composition API** - 使用 `<script setup>` 语法，代码更简洁
- ✅ **组合式函数** - 业务逻辑封装在 `composables/` 中，高复用
- ✅ **Pinia 状态管理** - 替代 Vuex，更好的 TypeScript 支持
- ✅ **类型安全** - 全面 TypeScript 化，编译时错误检查
- ✅ **分层架构** - pages → composables → store → services 清晰分层

---

## 📱 多端支持

| 平台 | 命令 | 说明 |
|------|------|------|
| H5 | `npm run dev:h5` | 浏览器运行 |
| 微信小程序 | `npm run dev:mp-weixin` | 微信开发者工具 |
| App | `npm run dev:app` | HBuilderX 真机/模拟器 |
| 支付宝小程序 | `npm run dev:mp-alipay` | 支付宝开发者工具 |
| 百度小程序 | `npm run dev:mp-baidu` | 百度开发者工具 |
| 抖音小程序 | `npm run dev:mp-toutiao` | 抖音开发者工具 |

---

## 💻 开发指南

### 代码规范

```bash
# ESLint 检查
npm run lint

# 自动修复
npm run lint:fix

# TypeScript 类型检查
npm run type-check
```

### 添加新页面

1. 在 `src/pages/` 下创建页面目录
2. 创建 `index.vue` 文件
3. 在 `src/pages.json` 中添加路由配置

```vue
<!-- src/pages/demo/index.vue -->
<script setup lang="ts">
import { ref } from 'vue'

const message = ref('Hello LedgerWise!')
</script>

<template>
  <view class="container">
    <text>{{ message }}</text>
  </view>
</template>

<style lang="scss" scoped>
.container {
  padding: 30rpx;
}
</style>
```

### 添加新 Store

```typescript
// src/store/demo.ts
import { defineStore } from 'pinia'
import { ref, computed } from 'vue'

export const useDemoStore = defineStore('demo', () => {
  const count = ref(0)
  const doubleCount = computed(() => count.value * 2)

  function increment() {
    count.value++
  }

  return { count, doubleCount, increment }
})
```

### 添加组合式函数

```typescript
// src/composables/useDemo.ts
import { ref } from 'vue'

export function useDemo() {
  const data = ref(null)
  const loading = ref(false)

  async function fetchData() {
    loading.value = true
    try {
      // 获取数据逻辑
    } finally {
      loading.value = false
    }
  }

  return { data, loading, fetchData }
}
```

---

## 📦 构建部署

### H5 部署

```bash
# 构建
npm run build:h5

# 产物在 dist/build/h5 目录
# 部署到 Nginx/静态服务器
```

### 小程序发布

```bash
# 构建微信小程序
npm run build:mp-weixin

# 产物在 dist/build/mp-weixin 目录
# 使用微信开发者工具上传
```

### App 打包

1. 使用 HBuilderX 打开项目
2. 点击 发行 → 原生App-云打包
3. 选择平台（Android/iOS）和证书
4. 等待打包完成

---

## 🤝 参与贡献

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

### 提交规范

```
feat:     新功能
fix:      Bug 修复
docs:     文档更新
style:    代码格式（不影响功能）
refactor: 代码重构
test:     测试相关
chore:    构建/工具链更新
```

---

## 📄 开源协议

本项目基于 [MIT License](LICENSE) 开源。

---

## 🙏 致谢

- [Vue.js](https://vuejs.org/) - 渐进式 JavaScript 框架
- [uni-app](https://uniapp.dcloud.net.cn/) - 跨平台应用开发框架
- [Pinia](https://pinia.vuejs.org/) - Vue 状态管理库
- [uCharts](https://www.ucharts.cn/) - 跨平台图表库

---

<div align="center">

**⭐ 如果这个项目对你有帮助，请给一个 Star 支持一下！⭐**

Made with ❤️ by [Agions](https://gitee.com/Agions)

</div>