# 记账簿 - LedgerFlow

**Repository Path**: lanyun417/ledger-flow

## Basic Information

- **Project Name**: 记账簿 - LedgerFlow
- **Description**: LedgerFlow 是一款个人记账与财务分析 Web 应用，采用前后端分离架构。前端基于 Vue 3 + TDesign 提供可视化收支看板，后端基于 Express + TypeScript 提供记账数据持久化与 AI 财报分析能力。数据按月份以 JSON 文件存储，无需数据库即可运行，适合快速部署到个人服务器或本地使用。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-09-01
- **Last Updated**: 2026-09-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: 记账簿, vue3, 财务, 流水, Nodejs

## README

# LedgerFlow

LedgerFlow 是一款个人记账与财务分析 Web 应用，采用前后端分离架构。前端基于 Vue 3 + TDesign 提供可视化收支看板，后端基于 Express + TypeScript 提供记账数据持久化与 AI 财报分析能力。数据按月份以 JSON 文件存储，无需数据库即可运行，适合快速部署到个人服务器或本地使用。

## 功能特性

- **收支记账**：新增 / 编辑 / 删除记录，字段包含收支类型、分类、金额、日期与备注。
- **分类管理**：内置工资、餐饮、交通等常用分类，支持自定义并持久化收藏的收支分类。
- **数据可视化**：总收入、总支出、结余三张统计卡片，类别占比环形图，近 6 个月收支趋势图。
- **列表筛选**：按月份、收支类型、备注关键词筛选，配合分页展示；记录默认按创建时间倒序排列。
- **AI 财报分析**：支持按月、按年、按区间或按全部时间分析，基于硅基流动 Qwen3-8B 模型生成消费洞察与理财建议。
- **访问密码**：通过 `LEDGER_ACCESS_PASSWORD` 启用访问密码，未登录时无法调用任何数据接口。
- **静态托管**：后端可直接托管前端构建产物，一个进程即可同时提供页面与接口，方便部署。

## 技术栈

| 层   | 技术                                                                                                                             |
| ---- | -------------------------------------------------------------------------------------------------------------------------------- |
| 前端 | Vue 3（Composition API + `<script setup>`）、TypeScript、Vite、TDesign Vue Next、ECharts、Tailwind CSS、Pinia、Vue Router、Axios |
| 后端 | Express 5、TypeScript、tsx、Node.js 原生 `fetch`                                                                                 |
| 存储 | 本地 JSON 文件（按月份拆分）                                                                                                     |
| AI   | 硅基流动（SiliconFlow）Qwen3-8B                                                                                                  |

## 目录结构

```
LedgerFlow
├── src/                      # 前端源码
│   ├── api/                  # 接口请求封装（axios）
│   ├── assets/styles/        # 全局样式（Tailwind 入口）
│   ├── components/           # 全局可复用组件
│   ├── composables/          # 组合式函数（数据获取逻辑）
│   ├── router/               # 前端路由
│   ├── stores/               # Pinia 状态
│   ├── types/                # 类型定义与常量
│   ├── utils/                # 工具函数（金额、日期）
│   ├── views/
│   │   ├── dashboard/        # 收支可视化主页
│   │   └── ai-analysis/      # AI 财报分析页
│   ├── App.vue
│   └── main.ts
├── server/                   # 独立后端
│   ├── data/                 # 持久化数据（按月 JSON，运行时自动创建）
│   ├── public/               # 前端构建产物托管目录
│   ├── index.ts              # Express 入口与路由
│   ├── store.ts              # 记录存储层（按月读写）
│   ├── categories.ts         # 分类清单存储层
│   ├── analysis.ts           # AI 财报分析（数据聚合 + 模型调用）
│   ├── types.ts              # 类型定义
│   ├── .env                  # 环境变量（API Key，已加入 gitignore）
│   └── API.md                # 后端接口文档
├── index.html
├── vite.config.ts
├── package.json
└── README.md
```

## 快速开始

### 环境要求

- Node.js `^22.18.0` 或 `>=24.12.0`
- npm

前后端为两个独立项目，需要分别安装依赖。开发时需要同时启动两个进程，前端默认监听 5173 端口，后端默认监听 3000 端口。

### 1. 安装依赖

在项目根目录安装前端依赖：

```sh
npm install
```

进入 `server` 目录安装后端依赖：

```sh
cd server
npm install
cd ..
```

### 2. 配置环境变量（可选）

编辑 `server/.env`，根据需要配置访问密码与 AI 分析：

```sh
# 访问密码（不配置或留空则跳过登录）
LEDGER_ACCESS_PASSWORD=你的访问密码

# AI 财报分析（硅基流动）
LEDGER_SILICONFLOW_API_KEY=你的_API_Key
```

Key 申请地址见 [硅基流动](https://siliconflow.cn)。`LEDGER_ACCESS_PASSWORD` 留空时开放访问、跳过登录；AI Key 未配置时，其余记账功能不受影响，仅 AI 分析接口会返回错误。

### 3. 启动后端

在项目根目录执行：

```sh
npm run server:dev
```

后端启动后监听 `http://localhost:3000`，接口基础路径为 `/api`。开发模式使用 `tsx watch`，修改代码后自动重启。

### 4. 启动前端

另开一个终端，在项目根目录执行：

```sh
npm run dev
```

浏览器会自动打开 `http://localhost:5173`。开发服务器已将 `/api` 请求代理到后端 3000 端口，因此前端代码无需感知跨域。

## 常用脚本

| 命令                 | 说明                                            |
| -------------------- | ----------------------------------------------- |
| `npm run dev`        | 启动前端开发服务器（Vite，自动打开浏览器）      |
| `npm run build`      | 类型检查并构建生产版本到 `dist`                 |
| `npm run preview`    | 本地预览构建产物                                |
| `npm run type-check` | 前端类型检查（vue-tsc）                         |
| `npm run format`     | 使用 Prettier 格式化 `src`                      |
| `npm run server`     | 启动后端（受 `.env` 的 `PORT` 影响，默认 3000） |
| `npm run server:dev` | 启动后端开发模式（热重载）                      |

## 环境变量

后端通过 `server/.env` 读取配置，该文件已被 `.gitignore` 忽略，请勿提交包含 API Key 的文件。

| 变量                          | 必填 | 默认值                          | 说明                                     |
| ----------------------------- | ---- | ------------------------------- | ---------------------------------------- |
| `LEDGER_ACCESS_PASSWORD`      | 否   | 无                              | 访问密码，配置后启用登录，留空则开放访问 |
| `LEDGER_SILICONFLOW_API_KEY`  | 否   | 无                              | 硅基流动 API Key，启用 AI 分析时必填     |
| `LEDGER_SILICONFLOW_BASE_URL` | 否   | `https://api.siliconflow.cn/v1` | AI 服务地址                              |
| `LEDGER_SILICONFLOW_MODEL`    | 否   | `Qwen/Qwen3-8B`                 | 使用的模型，可替换为同平台更强的模型     |
| `PORT`                        | 否   | `3000`                          | 后端监听端口                             |

## 数据存储

记账数据按月份拆分为多个 JSON 文件，存放在 `server/data` 目录，例如 `2026-09.json`。分类清单存放在 `server/data/categories.json`。数据目录会在首次写入时自动创建，删除某月全部记录后对应的月份文件也会被自动移除。

每条记录包含以下字段：

| 字段        | 类型                    | 说明                                 |
| ----------- | ----------------------- | ------------------------------------ |
| `id`        | `number`                | 记录唯一标识，服务端生成             |
| `type`      | `'income' \| 'expense'` | 收支类型                             |
| `category`  | `string`                | 分类                                 |
| `amount`    | `number`                | 金额（大于 0）                       |
| `date`      | `string`                | 日期，格式 `YYYY-MM-DD`              |
| `note`      | `string`                | 备注（可为空）                       |
| `createdAt` | `number`                | 创建时间戳（毫秒），列表按此字段倒序 |

完整的数据模型与接口定义见 [server/API.md](server/API.md)。

## AI 财报分析

首页右上角的「AI 财报分析」按钮会跳转到独立分析页面。分析流程分两层：

- **数据层**：后端先对所选时间范围内的记录做确定性聚合，计算收入、支出、结余、结余率以及分类占比，保证数字准确。
- **模型层**：将聚合结果交给 Qwen3-8B，仅让其基于结构生成定性的消费洞察与理财建议，不重复输出金额与百分比，避免模型幻觉产生错误数字。

分析范围支持按月、按年、按时间区间与按全部四种模式。

## 部署

后端可以将前端构建产物作为静态资源直接托管，从而实现单进程部署：

1. 构建前端：

   ```sh
   npm run build
   ```

2. 将 `dist` 目录下的内容复制到 `server/public`：

   ```sh
   # Windows PowerShell
   Copy-Item -Path dist\* -Destination server\public -Recurse -Force

   # macOS / Linux
   cp -r dist/* server/public/
   ```

3. 启动后端：

   ```sh
   npm run server
   ```

4. 访问 `http://localhost:3000` 即可使用完整应用。页面与接口同源，`/api` 请求无需代理转发。

## API 文档

后端接口的完整说明（请求参数、响应结构、错误约定）位于 [server/API.md](server/API.md)，包含记录增删改查、月度汇总、分类管理以及 AI 分析等接口。

# 项目效果

![alt text](screenshot/首页.jpeg)

![alt text](screenshot/记一笔.jpeg)

![alt text](screenshot/AI财报分析.jpeg)