# gift-ledger

**Repository Path**: Adnois/gift-ledger

## Basic Information

- **Project Name**: gift-ledger
- **Description**: 本地优先的礼金记账与人情往来管理桌面应用。Electron + React + TypeScript + Vite + ECharts，跨平台（macOS / Windows / Linux）。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-08
- **Last Updated**: 2026-09-08

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 礼金账本（Gift Ledger）

本地优先的礼金记账与人情往来管理桌面应用。Electron + React + TypeScript + Vite + ECharts，跨平台（macOS / Windows / Linux）。

## 功能

- **记账**：收礼 / 随礼流水，支持搜索、按类型/关系/年份筛选，按月份分组展示
- **往来**：按对方自动汇总「收 vs 随」，净差为正自动提醒待回礼；标注待回礼 / 人情未清 / 单向随礼等状态
- **统计**：收随总额与净结余卡片、月度/年度收支柱状图、按事由与关系分布、收/随礼 TOP 榜
- **设置**：导出 JSON 备份、导出 CSV（Excel 可打开）、导入 JSON 恢复、打开数据目录、清空数据

## 快速开始

```bash
npm install
npm run dev        # 构建渲染进程并用 Electron 打开应用
```

开发热更新（可选）：

```bash
npm run dev:hot    # 见下方说明
```

> 当前主进程默认加载构建产物（`dist/`）。如需开发热更新，可先运行 `npx vite` 启动
> 渲染服务，再设置 `ELECTRON_RENDERER_URL=http://localhost:5173` 后运行 `npx electron .`。

## 打包

```bash
npm run dist:mac     # macOS：dmg + zip
npm run dist:win     # Windows：nsis 安装包（需在 Windows 上执行）
npm run dist:linux   # Linux：AppImage
```

产物输出到 `release/`。macOS 打包如启用签名/公证，请参考 `electron-builder` 配置补充 `mac.identity` 或环境变量。

## 数据存储

- 数据文件：`lijin-data.json`，位于系统用户数据目录（macOS：`~/Library/Application Support/礼金账本/`）
- 全部数据仅存本机，不联网、不上传
- 金额以「分」为单位整数存储，避免浮点误差
- 设置页可随时导出 / 导入备份

## 技术栈

| 层 | 选型 |
| --- | --- |
| 壳 | Electron（contextIsolation + sandbox，无 nodeIntegration） |
| 渲染 | React 19 + Vite + TypeScript |
| 图表 | ECharts 6（按需引入 core 模块） |
| 持久化 | 主进程原子写 JSON（tmp + rename） |

## 目录结构

```
electron/        主进程 + preload（IPC 白名单）
src/
  lib/           工具、CSV、聚合统计
  pages/         记账 / 往来 / 统计 / 设置 / 记账表单
  components/    Modal、Confirm、EChart 封装
  store.tsx      数据上下文 + 防抖自动保存
```