# AI智能记账

**Repository Path**: HelloWorld114/smart-ledger

## Basic Information

- **Project Name**: AI智能记账
- **Description**: 一个功能完整的开源个人/家庭记账系统，包含前后端，支持多账户、多账本、AI智能记账、语音输入、OCR小票识别、数据报表、多人协同、预算管理、借贷跟踪等功能。
- **Primary Language**: NodeJS
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 1
- **Created**: 2026-07-22
- **Last Updated**: 2026-07-22

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 💰 Smart Ledger AI智能记账系统

一个功能完整的开源个人/家庭记账系统，包含前后端，支持多账户、多账本、AI智能记账、语音输入、OCR小票识别、数据报表、多人协同、预算管理、借贷跟踪等功能。

## 🎯 功能清单

### ✅ 核心记账功能
- [x] **多类型记录**：支出、收入、转账
- [x] **多账户管理**：现金、微信、支付宝、银行卡、信用卡、投资理财，支持自定义图标和类型
- [x] **二级分类体系**：
  - 11个支出一级分类（餐饮/交通/购物/娱乐/居住/医疗/教育/旅行/宠物/人情/其他）
  - 7个收入一级分类（工资/奖金/投资收益/兼职外快/红包礼金/退款报销/其他收入）
  - 3个转账一级分类（账户转账/信用卡还款/充值提现）
  - 每个一级分类下 4-9 个预置二级分类，共 80+ 个常用分类
  - 支持手动添加自定义二级分类
- [x] **商家/备注关联**：记账时自动补全(datalist)，新商家名自动创建
- [x] **账单日历视图**：按月展示每日收支汇总，点击日期查看当天明细
- [x] **高级筛选**：类型、日期范围、一级/二级分类多维度筛选
- [x] **快捷日期**：本月/上月/本年/去年一键筛选
- [x] **借贷中心**：借出/借入记录、分期还款跟踪、结清标记、联系人管理

### ✅ AI 智能记账（接入智谱 GLM-4-Flash / GLM-4V-Flash，免费模型）
- [x] **自然语言智能解析（NLP）**：输入"今天午餐外卖30元"自动识别类型/金额/分类/账户/日期/备注
- [x] **AI快捷记账栏**：账单页顶部输入框，说话/打字都能记，一键保存无需弹窗
- [x] **OCR 小票识别**：拍照/选图，使用 GLM-4V-Flash 多模态模型识别小票金额和商户
- [x] **语音记账**：🎤 语音说话自动转文字，再经过AI解析自动填充全表单，支持记账弹窗和账单页快捷栏
- [x] **AI 账单分析**：分析周/月/季/年账单，输出消费结构、问题识别、理财建议、财务健康评分（0-100）
- [x] **AI 分析历史**：每次分析结果自动保存，可随时查看过往分析记录
- [x] **异常消费检测**：对比近30天与前30天数据，自动发现支出突增的分类（>50%增长预警）和大额消费
- [x] **月底预测**：根据当月已过天数的日均消费，线性预测月底收支和结余
- [x] **智能预算推荐**：基于近3个月历史数据，AI 推荐下月分类预算和消费建议
- [x] **AI 设置**：在个人中心配置 API Key、模型名称、接口地址，支持文本模型和视觉模型分别配置

### ✅ 智能与快捷
- [x] **模板记账**：保存常用交易为模板，一键快速填充；记账时勾选"同时存为模板"，既保存记录又存模板
- [x] **小票图片上传**：记账时拍照保存凭证
- [x] **商家自动补全**：输入备注时datalist自动提示历史商家
- [x] **底部浮动按钮**：右下角紫色 FAB 快速打开记账弹窗

### ✅ 账本与协同
- [x] **多账本支持**：个人、家庭、旅行、生意等场景，新建账本自动初始化分类和账户
- [x] **多人协同**：邀请成员加入账本，支持编辑者/查看者权限
- [x] **账本图标自定义**：为每个账本选择emoji图标
- [x] **账本切换**：顶部下拉快速切换当前账本，数据按账本隔离

### ✅ 数据分析与报表
- [x] **首页概览**：月度收支结余卡片、预算进度条、支出排行Top5、最近5条记录、快捷入口
- [x] **四周期报表**：周报/月报/季报/年报，一键切换
- [x] **分类占比饼图**：支出/收入切换，自动聚合二级分类到一级
- [x] **分类排行榜**：Top支出分类进度条可视化
- [x] **每日收支趋势折线图**：双线对比收入支出，Canvas 绘制，DPR高清适配
- [x] **周期对比柱状图**：周/月/季/年不同维度的收支对比
- [x] **账户维度收支统计**：每个账户的收入/支出汇总
- [x] **预算管理**：月度总预算+分类预算，超支红色预警，进度条可视化
- [x] **净资产总览**：首页展示总资产、总负债、净资产

### ✅ 其他功能
- [x] 明/暗主题切换（LocalStorage持久化）
- [x] CSV 表格导出（UTF-8 BOM 支持Excel中文）
- [x] JSON 完整数据备份导出
- [x] 完全响应式移动端H5适配，支持iOS/Android
- [x] JWT 身份认证 + bcrypt 密码加密
- [x] 后端路由模块化，前端CSS/JS按页面拆分
- [x] 数据永久存储在你自己的服务器，API Key 仅保存在服务端
- [x] 新用户注册自动复制系统分类和默认账户

## 🛠️ 技术栈

- **后端**: Node.js + Express + MySQL (mysql2/connection pool)
- **前端**: 原生 HTML/CSS/JS（无框架依赖）
- **数据库**: MySQL 8.0+（支持5.7）
- **认证**: JWT + bcryptjs
- **AI**: 智谱 AI GLM-4-Flash（文本）/ GLM-4V-Flash（视觉OCR）
- **语音**: 浏览器原生 Web Speech API（中文）
- **图表**: 原生 Canvas 手写绘制（无Chart.js依赖）

## 🚀 部署步骤

### 1. 环境要求
- Node.js >= 18（使用原生 fetch 调用AI接口）
- MySQL >= 5.7
- 智谱AI API Key（免费注册：https://open.bigmodel.cn）

### 2. 初始化数据库
```bash
mysql -u root -p
```
```sql
source /smart-ledger/server/init-db.sql;
```
这会自动创建 `smart_ledger` 数据库、所有表结构，并初始化默认分类（80+个）和默认账户。

### 3. 配置数据库连接
编辑 `server/db.js`，修改为你的MySQL连接信息：
```javascript
const dbConfig = {
  host: 'localhost',
  user: 'root',
  password: 'your_password',
  database: 'smart_ledger',
};
```

### 4. 配置AI功能（可选）
启动应用后，在「我的 → AI智能助手」中填入：
- API地址：`https://open.bigmodel.cn/api/paas/v4/chat/completions`（默认已填）
- API Key：在智谱AI开放平台获取
- 文本模型：`glm-4-flash`（免费）
- 视觉模型：`glm-4v-flash`（免费）
- 开启AI功能开关

不配置AI也可以正常使用基础记账功能。

### 5. 安装依赖并启动服务
```bash
cd server
npm install
npm start
```
服务默认运行在 `http://localhost:3000`，直接在浏览器打开即可使用。
默认管理员账号：`admin` / `123456`（建议注册自己的账号）。

### 6. 生产环境部署
使用 PM2 进行进程管理：
```bash
npm install -g pm2
pm2 start server.js --name smart-ledger
pm2 save
pm2 startup
```

配置 Nginx 反向代理（可选）：
```nginx
server {
    listen 80;
    server_name ledger.yourdomain.com;
    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        client_max_body_size 10m;
    }
}
```

## 📱 使用方法速览

| 操作 | 方法 |
|------|------|
| 记一笔 | 点击右下角 + FAB |
| 语音记账 | 记账弹窗点 🎤 说一句话，或账单页快捷栏点 🎤 |
| AI文字记账 | 记账弹窗顶部AI框输入"打车25元"点解析，或账单页AI快捷栏 |
| 拍照识别小票 | 账单页AI快捷栏点 📷 拍照 |
| 查看日历 | 账单页点「📅日历」按钮 |
| 筛选账单 | 账单页点「🔍筛选」按钮，支持日期/分类筛选 |
| 查看报表 | 底部导航切到「报表」，选周报/月报/季报/年报 |
| AI分析报表 | 报表页点「🤖 AI智能分析」 |
| 切换账本 | 「我的」页面顶部下拉切换 |
| 邀请成员 | 「我的」→ 「成员管理」→ 邀请 |
| 导出数据 | 「我的」→ 「导出数据」|
| 深色模式 | 「我的」→ 切换深色模式开关 |

## 📂 项目结构

```
smart-ledger/
├── server/                     # 后端代码
│   ├── server.js               # Express 服务入口
│   ├── db.js                   # MySQL 连接池配置
│   ├── init-db.sql             # 数据库初始化脚本（表结构+80+系统分类+默认配置）
│   ├── package.json
│   ├── middleware/
│   │   └── auth.js             # JWT 认证 + 账本权限中间件
│   ├── routes/                 # 模块化路由
│   │   ├── auth.js             # 注册/登录/用户信息
│   │   ├── books.js            # 账本 CRUD、成员邀请
│   │   ├── accounts.js         # 账户管理
│   │   ├── categories.js       # 分类管理（二级，自动扁平旧三级分类）
│   │   ├── entities.js         # 商家/成员/项目管理
│   │   ├── records.js          # 收支记录 CRUD、列表/日历查询
│   │   ├── budgets.js          # 预算管理（总预算+分类预算）
│   │   ├── loans.js            # 借贷/还款管理
│   │   ├── reports.js          # 报表统计（饼图/排行/趋势/对比/账户）
│   │   ├── ai.js               # AI能力：分析/NLP解析/OCR/异常检测/预测/预算推荐/历史
│   │   ├── settings.js         # 系统配置（AI配置读写）
│   │   ├── upload.js           # 小票图片上传
│   │   └── export.js           # CSV/JSON 数据导出
│   └── uploads/                # 上传文件存储（自动创建）
│
└── public/                     # 前端静态文件（多页面架构）
    ├── index.html              # 首页（概览/预算/排行/最近记录）
    ├── login.html              # 登录/注册页
    ├── bills.html              # 账单明细页（列表+日历双视图+AI快捷栏）
    ├── accounts.html           # 账户管理页（净资产/账户CRUD）
    ├── reports.html            # 数据报表页（饼图/趋势/对比/AI洞察）
    ├── loans.html              # 借贷中心页
    ├── profile.html            # 个人中心页（账本/主题/导出/AI设置）
    ├── css/
    │   ├── common.css          # 公共样式：变量、重置、导航、弹窗、记账组件
    │   ├── login.css           # 登录页样式
    │   ├── home.css            # 首页样式
    │   ├── bills.css           # 账单页样式（日历/筛选/AI快捷栏）
    │   ├── accounts.css        # 账户页样式
    │   ├── reports.css         # 报表页样式（AI分析/洞察卡片）
    │   ├── profile.css         # 个人中心样式
    │   └── loans.css           # 借贷中心样式
    └── js/
        ├── common.js           # 公共库：状态/请求/认证/记账弹窗/语音/分类选择
        ├── home.js             # 首页逻辑
        ├── bills.js            # 账单页逻辑（列表/日历/筛选/AI快捷记账/OCR）
        ├── accounts.js         # 账户页逻辑
        ├── reports.js          # 报表页逻辑（AI分析/异常/预测/预算推荐/历史）
        ├── profile.js          # 个人中心逻辑（AI设置）
        └── loans.js            # 借贷中心逻辑
```

## 🔌 API 接口文档

### 基础接口

| 接口 | 方法 | 说明 |
|------|------|------|
| `/api/auth/register` | POST | 用户注册（自动创建默认账本+分类+账户） |
| `/api/auth/login` | POST | 用户登录 |
| `/api/auth/me` | GET/PUT | 获取/更新用户信息 |
| `/api/books` | GET/POST | 账本列表/创建 |
| `/api/books/:id` | PUT/DELETE | 更新/删除账本 |
| `/api/books/:id/invite` | POST | 邀请成员协同 |
| `/api/books/:id/members` | GET/DELETE | 查看/移除成员 |
| `/api/accounts` | GET/POST | 账户列表/创建 |
| `/api/accounts/:id` | PUT/DELETE | 更新/删除账户 |
| `/api/categories` | GET/POST | 分类列表（二级树）/创建 |
| `/api/categories/:id` | PUT/DELETE | 更新/删除分类 |
| `/api/entities` | GET/POST | 商家/项目列表/创建 |
| `/api/records` | GET/POST | 记录列表（支持类型/日期/分类筛选）/创建 |
| `/api/records/:id` | PUT/DELETE | 更新/删除记录 |
| `/api/budgets` | GET/POST/DELETE | 预算列表/设置/删除 |
| `/api/loans` | GET/POST | 借贷列表/创建 |
| `/api/loans/:id/repay` | POST | 记录还款 |
| `/api/loans/:id/settle` | POST | 标记结清 |
| `/api/reports/summary` | GET | 周期报表汇总（收支/分类/趋势/账户/对比） |
| `/api/upload/image` | POST | 小票图片上传 |
| `/api/export/csv` | GET | 导出 CSV 表格 |
| `/api/export/json` | GET | 导出 JSON 备份 |

### AI 接口

| 接口 | 方法 | 说明 |
|------|------|------|
| `/api/ai/analyze` | POST | AI账单分析（周/月/季/年），含财务健康评分，结果自动保存历史 |
| `/api/ai/parse` | POST | NLP自然语言解析，输入一句话返回结构化记账数据 |
| `/api/ai/ocr` | POST | 小票OCR识别（base64图片），使用GLM-4V-Flash视觉模型 |
| `/api/ai/anomaly` | POST | 异常消费检测（近30天vs前30天，>50%增长预警+大额消费日） |
| `/api/ai/predict` | POST | 月底收支预测（线性投影+AI点评） |
| `/api/ai/budget-recommend` | POST | AI智能预算推荐（基于3个月历史，返回分类预算+建议） |
| `/api/ai/history` | GET | AI分析历史列表（分页） |
| `/api/ai/history/:id` | GET/DELETE | 查看/删除单条历史分析 |

### 配置接口

| 接口 | 方法 | 说明 |
|------|------|------|
| `/api/settings/ai` | GET/PUT | 获取/更新AI配置（api_key安全隐藏） |

## 🗄️ 数据库表结构

| 表名 | 说明 |
|------|------|
| `users` | 用户账号（bcrypt加密密码） |
| `books` | 账本（多账本支持） |
| `book_members` | 账本成员（owner/editor/viewer 权限） |
| `accounts` | 资金账户（余额/类型/图标） |
| `categories` | 分类（二级层级，支持支出/收入/转账） |
| `entities` | 商家/成员/项目 |
| `records` | 收支流水（核心交易记录） |
| `budgets` | 月度预算（总预算+分类预算） |
| `loans` | 借贷记录（借出/借入） |
| `loan_records` | 还款记录 |
| `sys_config` | 系统配置（AI Key/模型等，全局） |
| `ai_analysis_history` | AI分析历史（持久化保存每次分析结果） |

## 🔒 数据安全

- 所有数据存储在你自己的服务器，不会上传到任何第三方
- AI API Key 仅保存在服务端数据库，前端接口返回时脱敏显示
- 密码使用 bcrypt 加密存储
- JWT token 有效期30天
- 所有API接口需要JWT认证，账本数据通过成员权限隔离
- 可自行配置 HTTPS 保证传输安全

## 🄯 License
MIT