GistLedger

GistLedger 是一个基于 GitHub Gist 的极简个人记账应用。它利用 GitHub Gist 作为免费、私有的云端数据库，实现数据的安全存储与多端同步。

体验地址: https://gist-ledger.knowsky404.com

🌐 核心理念: Own your data (数据隐私) | Serverless (无后端) | Lightweight (轻量化)

📸 项目预览

@e270057580df75c410c0ff3fef59ec9e56ad8832/docs/Transaction.PNG" width="32%" alt="Transaction Form" /> @e270057580df75c410c0ff3fef59ec9e56ad8832/docs/HistoryView.PNG" width="32%" alt="History View" /> @e270057580df75c410c0ff3fef59ec9e56ad8832/docs/StatisticsView.PNG" width="32%" alt="Statistics View" />

✨ 功能特性

1. 📝 极简记账 (Journal)

• 快速录入: 支持收入/支出切换，金额、分类、日期、备注一键录入。
• 最近记录: 首页实时展示最近 5 笔交易，方便快速核对。
• 完全私有: 数据仅存储在你的 GitHub Gist 中，无第三方服务器读取。

2. 📊 统计报表 (Statistics)

• 双重视图:
  • 月度视图: 聚焦本月收支，展示当年 12 个月的收支变化趋势，辅助判断本月消费水位。
  • 年度视图: 聚焦全年收支，展示近 5 年的长期收支变化趋势，掌握宏观财务健康状况。
• 多维筛选: 支持按分类（可多选）筛选统计数据，例如查看“餐饮”+“交通”的年度支出趋势。
• 动态图表: 交互式图表实时响应筛选和日期切换。

3. 🔍 查询管理 (Query)

• 多维筛选: 支持按类型（收入/支出）、日期范围、关键词（分类/备注）进行组合查询。
• 数据管理: 支持对历史记录进行修改或删除。
• 客户端分页: 即使数据量大也能流畅分页浏览。

🛠 技术栈

• 框架: React 19 + TypeScript
• 构建工具: Vite
• 样式: Tailwind CSS v4
• 图标: Lucide React
• API: Octokit (GitHub REST API)
• 部署: Cloudflare Pages / Vercel / GitHub Pages (纯静态部署)

🚀 快速开始

前置准备

1. 拥有一个 GitHub 账号。
2. 生成一个 GitHub Personal Access Token (Classic)。
   • Scope 权限: 必须勾选 gist 权限。

本地运行

# 1. 克隆项目
git clone https://github.com/KnowSky404/gist-ledger.git
cd gist-ledger

# 2. 安装依赖 (推荐使用 pnpm)
pnpm install

# 3. 启动开发服务器
pnpm dev

使用说明

1. 打开应用后，在登录页输入你的 GitHub Personal Access Token。
2. 点击 “连接数据库”。
   • 如果是首次使用，应用会自动在你的 Gist 中创建一个名为 GistLedger-Data 的私有 Gist 和 ledger_data.json 文件。
   • 如果已有数据，会自动同步拉取。
3. 开始记账！你的 Token 和 Gist ID 会保存在本地浏览器缓存中，下次访问无需重复输入（除非清除缓存或点击退出）。

🔒 数据安全

• 应用不会将你的 Token 发送给除 GitHub API 以外的任何服务器。
• 数据存储在你的私有 Gist 中，只有拥有该 Token 的人才能访问。
• 建议定期备份 Gist 数据或使用 GitHub 的版本历史功能回滚误操作。

📄 License

GNU General Public License v3.0 (GPL-3.0)