# Ledgerly

**Repository Path**: note-vue/ledgerly

## Basic Information

- **Project Name**: Ledgerly
- **Description**: 本地记账工具
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-25
- **Last Updated**: 2026-09-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: electron-egg, Vue, Nodejs

## README

# Ledgerly 本地记账工具（electron-egg + Vue3）

基于 [electron-egg](https://www.kaka996.com/) + Vue3 的本地记账桌面应用，左侧导航按一级分组 + 二级菜单组织（分组可折叠：点击分组标题展开 / 收起，各分组独立展开互不影响）；**首页**（置顶）→ **记账与计划**（流水明细 / 存款计划）→ **智能工具**（AI 分析 / 百度搜索）→ **数据维护**（字典维护 / 数据清理 / 导出数据 / 修改记录）→ **文档说明**（更新记录 / 功能说明 / 操作说明书）→ **设置**。

- **首页**：本月收入、支出、结余、存款差额、计划存款进度、最高消费、支出分类 Top5 总览看板
- **流水明细**：记账已融合到明细页（工具栏「＋ 新增记录」直接录入收入 / 支出）；类型 / 分类（与类型联动）/ 日期区间筛选，分页表格，支持修改与删除（留痕）
- **导出数据**：流水导出（收入 / 支出类型、金额、时间，支持日期筛选与类型过滤）与长期计划导出（年度 / 三年 / 五年），支持文本（.txt）与图片（.png）；导出时弹出系统保存对话框选择路径，保存完成后提示成功
- **存款计划**：月度计划按结余对比；年度 / 三年 / 五年计划按目标周期累计结余跟踪进度（可设备注，如购房首付）；长期计划支持**历史收入补录**（按**年份**补录年度收入，同一年可多次补录自动累加）；年度 / 三年 / 五年各类型「统计期前补录」开关**相互独立**：区间内历史收入补录始终计入累计结余，开关控制是否额外统计起始年之前的补录（结束年之后的补录不计入），首页长期计划卡片统计口径同步联动
- **字典维护**：维护收支类型与收支分类（增删改、排序、引用保护、恢复默认/初始化），记账、明细、计划全链路统一使用
- **AI 分析**：基于月度统计汇总调用豆包大模型（火山方舟 API）生成消费结构、异常提示、存款评估与优化建议
- **百度搜索**：主进程直连百度抓取（会话 Cookie 规避风控），结果在当前页面内以列表展示（大连房价、公积金等快捷词），可一键在系统浏览器打开
- **修改记录**：流水（收入 / 支出）与存款计划的修改、删除操作自动留痕，按「支出修改 / 收入修改 / 计划修改」分类查看
- **更新记录**：独立页面（`/updates`）时间线展示版本更新历史，直接读取内置种子（`electron/assets/changelogs.default.json`，随安装包分发，只读）；独立运行数据存储于 `data/changelogs.json`，更新 / 清理 / 备份恢复不影响（更新日志维护页已隐藏，代码保留）
- **数据清理**：批量删除收入 / 支出 / 计划等记录；支出与长期计划支持**多选批量删除**；长期计划（年度 / 三年 / 五年）支持**按类型单独清理**；每次清理前提示**是否需要备份**（先备份再清理 / 直接清理）；清理动作写入「修改记录」留痕，分类字典与更新日志保留
- **备份 / 还原**：全部 jsondb 库统一备份为单文件节点（`ledgerly-backup-{原因}-{时间}.json`）；「还原数据」支持选择历史备份节点还原，还原前自动备份当前数据；导出 / 导入 / 更新 / 清理前均自动备份
- **系统托盘**：关闭窗口可最小化到托盘（单击/双击托盘图标恢复窗口），也可设置直接退出
- **功能说明**：静态页面，逐一描述每个页面功能与数据安全机制（纯说明，无需数据维护）
- **操作说明书**：静态页面，按功能分区给出具体操作步骤（首次使用、记账、存款计划、导出、AI、搜索、字典、清理、备份还原、设置），并附各功能页面截图
- **设置**：AI 配置（API Key / 模型 / 接口地址）+ 窗口关闭行为 + 导入导出、备份 / 还原、更新记录、检查更新、云备份 / 云同步
- **界面语言**：Element Plus 已配置为中文（zh-cn locale）
- **操作确认**：所有修改 / 删除均有可关闭的确认框，确认后自动留痕
- **品牌图标**：窗口 / 托盘 / 浏览器标签 / 应用内 Logo 统一使用 FJG 图标
- **界面体验**：全局滚动条极简美化（保留滚动功能）
- **当前版本**：0.2.5（记账融合流水明细、导出数据页、统计期前补录开关等，详见「更新记录」页）

## 功能

### 首页（记账总览看板）
- **统计卡**：本月收入 / 支出 / 结余 / 存款差额（自动按选中月份计算）
- **计划存款进度**：结余 ÷ 计划金额的环形进度，实时状态（达标 / 缺口 / 未设置）
- **最高消费**：本月单笔最大支出（分类 + 日期），附占支出比例提示
- **支出分类 Top5**：分类占比进度条
- **长期计划卡片**：年度 / 三年 / 五年计划进度卡片（目标周期、累计结余、进度），期前补录未计入时显示「期前补录 X 元（未计入）」提示，统计口径随「存款计划」各类型开关联动
- **快捷入口**：AI 分析跳转、百度搜索（含「大连房价 / 大连公积金 / 大连购房政策 / 公积金贷款」快捷词）

### 记账录入（已融合到流水明细）
- 记账入口已合并至「流水明细」页：工具栏「＋ 新增记录」弹窗直接录入收入 / 支出，原「记账」页面代码保留、路由重定向到明细页
- 录入字段：支出 / 收入切换（类型自动切换分类列表，分类支持自定义输入）、金额、日期（默认今天）、备注
- 保存后写入 `data/ledger.json` 的 accounts 表

### 流水明细
- 新增：工具栏「＋ 新增记录」直接录入收入 / 支出（记账融合于此）
- 筛选：类型、分类、日期区间
- 表格：日期 / 类型 / 分类 / 金额 / 备注 / 操作（编辑、删除）
- 分页（每页 10 条）

### 存款计划
- **月度计划**：按月设置计划存款金额，实时对比结余与差额（达标 / 缺口），历史月度计划表
- **年度计划 / 三年计划 / 五年计划**：以起始年为起点，按目标周期（1 / 3 / 5 个自然年）累计结余（各月收入 - 支出之和）对比目标金额
  - 设置目标：起始年份、目标金额、备注（如购房首付）
  - 进度展示：目标周期、目标金额、区间累计结余、差额、状态（达标 / 进行中）+ 进度条
  - 历史目标列表：可查看进度与删除；同类型同起始年保存即覆盖

### 导出数据
- 入口：导航「数据维护 → 导出数据」（`/export`），独立页面
- **流水导出**：
  - 支持**日期筛选**（起止日期）与**类型过滤**（收入 / 支出 / 全部），默认导出当前筛选结果全部流水
  - 导出内容包含收入 / 支出**类型、分类、金额、时间、备注**，并自动汇总区间**收入 / 支出 / 结余**
- **长期计划导出**：
  - 年度 / 三年 / 五年计划全部导出，每条含目标周期、目标金额、累计结余、历史收入补录、差额、进度、状态、备注
- **导出格式**：文本（.txt）与图片（.png，Canvas 绘制表格）两种
- **保存方式**：点击导出弹出**系统保存对话框**选择保存路径，**保存完成后提示「导出成功 + 路径」**；用户取消时静默不提示
- 全部在本地生成，不经过网络

### AI 分析
- 选择月份 →「生成分析」调用大模型；「重新生成」覆盖旧报告
- 报告内容：收支概况、消费结构、异常提示、存款评估、优化建议（结构化渲染）
- 历史报告按月留存，可随时查看
- **首次使用需到「设置 → AI 分析配置」填写豆包 API Key**（火山方舟控制台创建），模型默认 `doubao-1.5-pro-32k-250115`，接口默认 `https://ark.cn-beijing.volces.com/api/v3/chat/completions`

### 百度搜索
- **页面内展示**：主进程直连百度抓取搜索结果（`electron/service/searchService.js`），先获取会话 Cookie 规避百度图形验证码风控，再请求搜索页并解析为结构化列表
- 结果列表渲染：标题 / 摘要 / 来源域名卡片，点击条目通过主进程 `shell.openExternal` 在系统浏览器打开原文
- 快捷词一键搜索（大连房价 / 大连公积金 / 大连购房政策 / 公积金贷款）；「在系统浏览器中打开完整搜索页」按钮保留
- 浏览器开发预览（无 Electron 环境）下自动降级为 `window.open` 打开
- 说明：早期版本使用 `<webview>` 内嵌百度，在当前环境加载被拦截（ERR_FAILED），已改为主进程抓取方案

### 字典维护
- **收支类型**：维护类型值（数字标识）与类型名称（如收入 / 支出），新增、修改、删除；被分类或流水引用时禁止删除
- **分类管理**：按收支类型维护记账分类（名称、排序），新增、修改、删除；被流水引用时禁止删除
- **恢复默认 / 初始化**：一键恢复内置默认字典（2 类型 + 13 分类），已被流水引用的分类 / 类型自动保留；首次安装数据为空时可一键初始化
- **联动生效**：记账页、明细页的分类与类型选项统一读取同一字典；修改分类名称时自动同步更新已记账流水（按 类型 + 旧名 匹配，防跨类型同名误改）；流水明细筛选支持类型 → 分类联动

### 数据清理
- **记录概览**：收入 / 支出 / 月度计划 / 年度计划 / 三年计划 / 五年计划 / 历史收入补录 / AI 报告实时计数
- **支出多选批量删除**：勾选多条支出流水后批量删除（合计金额提示），也可清空全部支出
- **计划分类清理**：月度计划、年度计划、三年计划、五年计划**按类型分别清空**，或一次性清空全部长期计划
- **长期计划多选批量删除**：年度 / 三年 / 五年计划可混合勾选批量删除
- **其他清理**：历史收入补录、AI 分析报告、全部业务数据
- 每次清理前两步确认（清理范围 → 是否需要备份）；清理动作写入「修改记录」留痕；分类字典与更新日志保留

### 备份 / 还原（设置）
- **备份格式**：全部 jsondb 库（ledger / changelogs / settings 等）打包为单个节点文件 `ledgerly-backup-{原因}-{时间戳}.json`；旧版单库备份（`demo-*.json`）仅兼容展示，不可还原
- **备份列表**：展示节点类型（全库 / 旧版）、原因、大小、时间；保留最近 10 个节点
- **还原数据**：选择「全库」历史节点还原（还原前自动备份当前数据，完成后重启应用生效）
- **导出 / 导入**：导出为单文件（全部库）；导入覆盖前自动备份，完成后重启应用生效

### 操作说明书
- 入口：导航「文档说明 → 操作说明书」（`/manual`）
- 内容：按功能分区给出**具体操作步骤**（首次使用 / 记账与流水 / 存款计划 / 导出数据 / AI 分析 / 百度搜索 / 字典维护 / 数据清理 / 备份还原与云同步 / 设置与系统 / 修改记录与文档说明），每个分区附**对应页面截图**
- 静态说明，不涉及数据维护，与「功能说明」互为补充

### 修改 / 删除留痕
- 流水（收入 / 支出）与存款计划（月度 / 年度 / 三年 / 五年）的修改、删除操作均自动写入操作记录（`opLogs` 表）
- 确认框可关闭（取消按钮文案为「关闭」），并展示变更摘要与「修改后将记录到修改记录页面」提示
- **修改记录页**（`/changes`）：按「支出修改 / 收入修改 / 计划修改」三个 Tab 分类查看，分页展示操作时间、字段变更前后值

### 系统托盘
- 关闭窗口行为可在「设置 → 窗口关闭行为」中选择：**最小化到托盘**（默认，后台继续运行）或 **直接退出应用**
- 托盘图标单击 / 双击可恢复主窗口；右键菜单含「打开 Ledgerly」「退出」
- 托盘图标与应用图标统一为 FJG 品牌图标（`public/images/logo-32.png`）

### 设置（数据导入导出）
- **导出**：弹窗选择保存路径，导出**全部 jsondb 库**（记账 / 计划 / 更新日志 / 设置）为单个 JSON 文件
- **导入**：弹窗选择 JSON 文件整体覆盖全部数据（**导入前自动备份当前数据**，完成后需重启应用生效）

### 设置（备份管理）
- **备份路径配置**：可自定义备份目录（留空则用默认 `userData/ledgerly-backup`），保存后立即生效
- **立即备份**：手动备份**全部 jsondb 库**为单文件节点
- **备份列表**：展示节点类型（全库 / 旧版）、原因、大小、时间，可一键打开备份目录
- **还原数据**：备份列表内「还原」按钮，选择历史「全库」节点还原（还原前自动备份当前数据）
- 自动保留最近 10 个备份节点，更早的自动清理

### 设置（检查更新）
- 点击「检查更新」，主进程先**自动备份全部 jsondb 库**，再检查新版本
- 发现新版本 → 自动下载（显示进度）
- 下载完成 → 提示安装，**安装前再次备份全部 jsondb 库**并写入恢复标记
- 更新完成重启 → **自动从最新全库备份恢复**，删除恢复标记

### 设置（云备份 / 云同步）
- **云备份**：把**全部 jsondb 库**打包为单载荷上传到配置的云地址（与本地备份同构）
- **云同步**：从云端下载全库载荷并整体覆盖本地全部数据（覆盖前自动备份当前数据，完成后重启应用生效）
- **自动云备份**：开启后按设定间隔（分钟）自动执行云备份，设置保存后立即生效，重启后自动恢复
- 云接口为通用 REST 约定（需自建或使用对象存储网关）：
  - `PUT {endpoint}` 上传：body 为全库载荷 JSON（`{ _meta: { reason, createdAt, appVersion, dbs }, [库名]: state, ... }`），Header `Authorization: Bearer <token>`
  - `GET {endpoint}` 下载：返回最近一次上传的全库载荷 JSON

## 更新机制说明

- 更新基于 `electron-updater`（generic provider），更新源在 `electron/config/builder.json` 的 `publish.url` 中配置：
  ```json
  "publish": {
    "provider": "generic",
    "url": "https://your-update-server.com/ledgerly/"
  }
  ```
  **上线前请将 url 替换为你的真实更新服务器地址**，并把新版本安装包（NSIS exe + latest.yml + blockmap）上传到该目录。更新服务器 Nginx 配置见 `deploy/nginx-update.conf`（静态托管 + 缓存治理 + Range 支持，含反向代理模式）。
- 默认备份目录：`userData/ledgerly-backup/`（userData 即 `C:\Users\<用户名>\AppData\Roaming\<应用名>`），不随应用安装目录更新被覆盖；也可在设置中自定义。
- **备份格式**：`ledgerly-backup-{原因}-{时间戳}.json` 单文件全库（包含 ledger / changelogs / settings 等全部 jsondb）；旧版 `demo-*.json` 单库备份仅兼容展示。
- 恢复时机：应用启动（`electron/index.js` 的 `electronAppReady`）时检测恢复标记，存在则用最新全库备份逐库同步回 `data/` 目录。
- 开发环境（未打包）下「检查更新」会提示跳过，属正常现象。

## 技术说明

- 主进程控制器：`electron/controller/ledger.js`（记账/统计/存款计划/AI 分析/字典/操作记录/更新日志/批量删除/数据清理）、`export.js`（导出保存对话框）、`dbJson.js`（增删改查/导入导出）、`update.js`（检查更新）、`settings.js`（设置/备份/云）、`search.js`（百度搜索）、`navigation.js`（窗口/打开外链）
- 业务服务：`electron/service/ledger.js`（记账数据/字典/操作记录）、`searchService.js`（百度抓取解析）、`aiClient.js`（豆包大模型调用）、`dbJson.js`、`settings.js`
- 工具：`electron/utils/ledgerCalc.js`（记账统计纯函数 + AI 提示词组装）、`updater.js`（**全库备份 / 还原 / 导出 / 导入 / 更新**）、`cloud.js`（**全库云备份 / 云同步 / 自动云备份**）
- 数据存储：`ee-core/storage` 的 jsondb 驱动：
  - `data/ledger.json`：记账业务数据（accounts / categories / savingPlans / goalPlans / dictTypes / aiReports / opLogs / incomeAdjustments）
  - `data/changelogs.json`：更新日志（独立文件，与业务数据隔离；首次安装自动导入内置种子 `electron/assets/changelogs.default.json`）
  - 备份 / 还原 / 导出 / 导入 / 更新统一为**全库**操作（data 目录下所有 jsondb 库），不再操作脚手架 demo 数据
  - `data/demo.json`：保留的 users 表
  - `data/settings.json`：应用设置（备份路径、关闭行为、云配置、AI 配置）
- 打包说明：`builder.json` 的 `files` 显式排除 `data/`（运行时数据不打进安装包），内置更新日志种子位于 `electron/assets/changelogs.default.json`（随 app.asar 分发）
- 渲染进程：Vue3 + Element Plus（中文 locale），IPC 频道定义在 `frontend/src/api/main.js`
- 所有接口返回统一响应体 `{ code, msg, data }`（见 `electron/utils/resUtil.js`）

## 上手指南

#### 安装依赖

```bash
# 根目录，安装 electron 依赖
npm i

# 进入【前端目录】安装 frontend 依赖
cd frontend
npm i
```

#### 启动项目

- 同时启动 frontend (UI) 、electron 两个服务

```bash
npm run dev
```

- 分开启动 frontend (UI) 、electron

```bash
# 打开两个终端
npm run dev-frontend

npm run dev-electron
```

- 构建前端资源

```bash
npm run build-frontend
```

## 文件目录说明

```
project
├── main.js                入口文件（package.json main 指向，ee-bin 启动）
├── package.json           npm 包配置（dev / build / build-w 等脚本）
├── electron               主进程服务
│   ├── index.js           主进程入口（应用生命周期、窗口创建、系统托盘、关闭行为）
│   ├── config             配置文件（builder.json 打包与更新源、config.default.js 窗口配置、config.local.js / config.prod.js、bin.js、nodemon.json）
│   ├── controller         控制器（IPC 频道：ledger 记账/字典/操作记录、export 导出保存、search 百度搜索、dbJson 数据、update 更新、settings 设置/备份/云、navigation 窗口/外链）
│   ├── service            业务层（ledger 记账、searchService 百度抓取、aiClient AI 调用、dbJson、settings）
│   ├── assets             内置资源（changelogs.default.json 更新记录种子，随安装包分发，供「更新记录」页只读展示）
│   ├── preload            预加载脚本（bridge.js 桥接、index.js）
│   └── utils              工具（resUtil 响应体、ledgerCalc 记账统计纯函数、updater 全库备份/还原/更新、cloud 云备份/云同步）
├── frontend               前端目录（Vue3 + Element Plus 中文 locale）
│   ├── index.html         入口 HTML（标题 + favicon 品牌图标）
│   ├── vite.config.js     Vite 构建配置
│   ├── .env.development   开发环境变量
│   ├── .env.production    生产环境变量
│   ├── dist               前端构建产物
│   └── src
│       ├── api            IPC 频道定义（controller.* 频道集中管理）
│       ├── assets         静态资源（LOGO-FJG.png 品牌图、global.less 全局滚动条样式）
│       ├── components     公共组件
│       ├── layouts        窗口布局（标题栏 + 侧边导航）
│       ├── router         路由（首页/明细/存款计划/字典/AI分析/百度搜索/导出数据/修改记录/更新日志[隐藏，代码保留]/更新记录/数据清理/功能说明/操作说明书/设置）
│       ├── utils          通用工具（金额格式化等）
│       ├── views          页面视图：home 首页、ledger 记账（代码保留，路由重定向到明细）、list 流水明细、plan 存款计划、dict 字典维护、ai AI分析、search 百度搜索、export 导出数据、changes 修改记录、changelog 更新日志（隐藏，代码保留）、updates 更新记录、cleanup 数据清理、help 功能说明、manual 操作说明书、settings 设置
│       ├── App.vue        根组件
│       └── main.js        前端入口（Element Plus 中文 locale、图标全局注册）
├── data                   jsondb 数据文件（运行时读写，打包时排除）
│   ├── ledger.json        记账数据库（accounts/categories/savingPlans/goalPlans/dictTypes/aiReports/opLogs/incomeAdjustments）
│   ├── changelogs.json    更新日志（独立文件；首次安装自动导入内置种子）
│   ├── demo.json          框架保留数据库（users 表）
│   └── settings.json      应用设置（AI 配置、备份路径、窗口关闭行为、云配置）
├── electron/assets        changelogs.default.json 内置更新日志种子（打包进 app.asar）
├── public                 渲染进程静态资源
│   ├── images             品牌图标（logo.png / logo-32.png / logo-32-ee.png）
│   ├── html               页面资源
│   ├── ssl                证书文件
│   └── dist               静态资源构建产物
├── build                  打包相关资源
│   ├── icons              FJG 品牌图标（icon.ico / icon.icns / 多尺寸 png）
│   ├── extraResources     额外资源（随应用分发）
│   └── script             安装脚本（installer.nsh）
├── deploy                 nginx-update.conf 更新服务器 Nginx 配置
├── docs                   设计文档
│   ├── prototypes         6 张 Axure 风格原型图（p1_home ~ p6_search）
│   └── build-prototypes.py 原型图生成脚本（PIL，可重跑）
├── out                    打包输出目录（安装包 + latest.yml + blockmap）
├── logs                   运行日志（运行时生成）
└── test-*.js              单测脚本（test-ledgerCalc.js 记账统计纯函数等）
```

## 使用到的框架

- [electron-egg](https://www.kaka996.com/pages/a28da5/)
- [vue3](https://cn.vuejs.org/guide/introduction.html)
- [Element Plus](https://element-plus.org/)