# ExpenseTracker

**Repository Path**: jeffrylee/expense-tracker

## Basic Information

- **Project Name**: ExpenseTracker
- **Description**: ExpenseTracker
一个用于“按账期记录支出 / 预算控制 / 统计分析”的前端应用，默认使用 Supabase 作为数据与鉴权后端；也支持切换到本地 MySQL + Express API 的数据源。
- **Primary Language**: NodeJS
- **License**: AGPL-3.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-31
- **Last Updated**: 2026-02-07

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ExpenseTracker（支出记账）

> 本项目采用 [GNU Affero General Public License v3.0](https://www.gnu.org/licenses/agpl-3.0.html) 协议：允许个人/组织**免费、开源**使用、修改与再分发；**禁止闭源商用**，衍生作品必须**开源**并**提供源代码**。

一个用于“按账期记录支出 / 预算控制 / 统计分析”的前端应用，默认使用 Supabase 作为数据与鉴权后端；也支持切换到本地 MySQL + Express API 的数据源。

## 产品特色（解决的痛点）

1. 账期化管理：把流水按“账期”自动归拢与汇总，解决跨月对账、结算口径不统一的问题。
2. 预算进度可视化：支持每日预算 + 分类预算 + 账期/月度模式，进度与差额一眼可见，解决“花到哪了、还剩多少”不清晰的问题。
3. 统计与列表联动：分类预算详情与分类管理保持一致，避免展示缺失/数量不一致，解决“同一份数据两处看不一样”的困扰。
4. 归档只读快照：账期可归档为只读，查看历史不怕误改，解决“历史数据被误操作、难以追溯”的问题。
5. 批量改类与导入：支持批量编辑分类、账单导入（微信/其他适配器），解决“整理历史账单耗时、改类改到手酸”的问题。
6. 数据源可切换：默认 Supabase，亦可切换本地 MySQL + Express（配合 SQL 导出），解决“想自托管/本地落库/迁移备份”的需求。

## 主要功能

- 记账：新增/编辑/删除支出与收入，支持备注与“我/家人”消费者
- 账期：按账期筛选与汇总，支持将账期数据归档为只读快照
- 预算：每日预算、分类预算、账期/月度模式
- 统计分析：分类维度的预算对比与差额展示
- 分类：分类管理与排序（用于预算与统计展示一致性）
- 批量编辑：按条件批量修改分类
- 导入：账单导入（含微信/其他适配器）
- 导出：一键导出 MySQL SQL 备份（用于本地落库或迁移）

## 技术栈概览

- 前端：React + Vite + TypeScript + TailwindCSS
- UI：Radix UI（shadcn/ui 风格组件）+ lucide-react + sonner
- 数据源：
  - Supabase（Postgres + Auth）
  - 可选：本地 Express + MySQL（`server/`）

## 快速开始（Supabase）

1) 安装依赖

```bash
npm install
```

2) 配置环境变量（Vite）

- `VITE_SUPABASE_URL`
- `VITE_SUPABASE_ANON_KEY`

3) 启动开发环境

```bash
npm run dev
```

4) 构建

```bash
npm run build
```

## 切换到本地 MySQL 数据源（可选）

1) 启动本地 API（Express）

```bash
cd server
npm install
cp .env.example .env
npm run dev
```

2) 前端配置数据源（Vite）

- `VITE_DATA_PROVIDER=mysql`
- `VITE_MYSQL_API_URL=http://localhost:3000/api`

前端的数据源选择逻辑在 `src/app/services/api/dataProvider.ts`（默认 `supabase`）。

## “提示词/AI 文档资产”说明

仓库内存在用于 AI 协作/需求沉淀的文档资产（例如 `/.trae/documents/` 与 `guidelines/Guidelines.md`），用于记录 PRD、页面规范、技术方案等结构化上下文；当前代码仓库中未发现任何运行时的 AI/LLM 调用逻辑（如 OpenAI/Claude/Gemini SDK、提示词模板渲染或模型网关接入）。

## 目录结构（核心）

- `src/app/App.tsx`：应用主入口（鉴权门禁、账期、导入/导出、预算概要与 Tab 切换）
- `src/app/hooks/useExpenses.ts`：核心数据与预算状态（加载、归档、账期预算读取、同步重试等）
- `src/app/components/`：主要业务组件（列表、表单、统计、预算设置、导入等）
- `src/app/services/`：数据源与导入适配（Supabase/MySQL Provider、WeChat/Other Adapter）
- `src/lib/supabase.ts`：Supabase Client 初始化（读取 `VITE_SUPABASE_*`）
- `supabase/migrations/`：数据库迁移（表结构、RLS、导入相关表、归档/分类/账期预算等）
- `server/`：本地 MySQL API（可选数据源）

## 版本更新（按 Git 提交）

> 仓库当前未打 Tag，以下以关键提交作为“版本节点”。

### 2026-01-30 · 0264453 · feat: 预算分析与UI优化，修复账期预算加载

- 预算分析与列表 UI：记录列表改为信息同排、压缩高度；统计页预算详情更易用
- 交互与可用性：统计设置支持折叠/展开；移动端预算详情滚动不带动页面
- 预算展示修复：分类预算进度条“实际金额”标签样式/定位与溢出问题修复
- 数据一致性：分类列表数量与预算/统计展示一致；修复“账期预算加载导致预算分配被清空”
- 归档与账期：新增/完善归档与账期预算相关迁移（见 `supabase/migrations/*archives*`、`*period_budgets*`）
- 文档资产：补齐 UI 改版 PRD/页面规范/技术方案（`/.trae/documents/ui_revamp_*`）

### 2026-01-30 · 3a74937 · 优化系统功能和UI，支持每日预算，账期数据归档等功能

- 新增每日预算与预算设置完善（预算模式、分类预算等）
- 增加账期归档能力（将历史账期快照化、只读化）
- 增加导入能力与相关数据表迁移（导入配置/明细等）
- 增加可切换的数据源抽象：Supabase 与本地 MySQL API（`VITE_DATA_PROVIDER`）
- 增加本地 MySQL 后端（`server/`），并提供导出 MySQL SQL 的工具能力

### 2026-01-03 · 71affc1 · 已完成 MySQL 本地部署支持的相关功能开发

- MySQL 本地部署适配收尾（ExpenseDialog 小幅调整）

### 2025-12-31 · e7f68b6 · 初始化提交:新建记录;统计分析;基础设置

- 完成记账主流程：新增/编辑记录、统计分析、基础设置
- 初始 Supabase 集成、UI 组件库与基础迁移