# AI智能记账

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

## Basic Information

- **Project Name**: AI智能记账
- **Description**: 一个功能完整的开源个人/家庭记账系统，包含前后端，支持多账户、多账本、AI智能记账、语音输入、OCR小票识别、数据报表、多人协同、预算管理、借贷跟踪等功能。系统同时提供 PC 端（侧边栏+顶栏桌面布局）和 H5 移动端（底部导航响应式布局），微信小程序端待验证，两套页面 CSS/JS 完全隔离独立维护，共享同一套后端 API。
- **Primary Language**: NodeJS
- **License**: MulanPSL-2.0
- **Default Branch**: master
- **Homepage**: https://izhangben.xunnan.net/pc/index.html
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 3
- **Created**: 2026-10-02
- **Last Updated**: 2026-10-02

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

**🌐 语言 / Language:** [中文](README.md) | [English](README.en.md)

# 💰 Smart Ledger AI智能记账系统

一个功能完整的开源个人/家庭记账系统，包含前后端，支持多账户、多账本、AI智能记账、语音输入、OCR小票识别、数据报表、多人协同、预算管理、借贷跟踪、还款自动提醒等功能。系统同时提供 **PC 端**（侧边栏+顶栏桌面布局）和 **H5 移动端**（底部导航响应式布局），两套页面 CSS/JS 完全隔离独立维护，共享同一套后端 API。

🌐 **在线体验地址**：
- 📱 **H5 移动端**：[https://izhangben.xunnan.net/login.html](https://izhangben.xunnan.net/login.html)
- 💻 **PC 桌面端**：[https://izhangben.xunnan.net/pc/index.html](https://izhangben.xunnan.net/pc/index.html)

（体验账号密码：`admin` / `123456`）
> 💡 推荐在登录页自己注册新账号，方便保护个人隐私数据
>
> ⚠️ 请大家不要修改默认体验账号密码，免得影响别人体验，感谢支持！
>
> 🛡️ 项目博主承诺长期维护，请大家放心使用！如遇访问异常或有功能建议，欢迎通过反馈中心或 Issue 告知。

**代码仓库开源地址**：
- GitHub：[https://github.com/xiangxiang088/smart-ledger.git](https://github.com/xiangxiang088/smart-ledger.git)
- Gitee：[https://gitee.com/xiangxiang088/smart-ledger.git](https://gitee.com/xiangxiang088/smart-ledger.git)
- GitCode：[https://gitcode.com/13128572534/smart-ledger.git](https://gitcode.com/13128572534/smart-ledger.git)


## 🎯 1.功能清单

### ✅ 1.1 核心记账功能
- [x] **多类型记录**：支出、收入、转账
- [x] **多账户管理**：现金、微信、支付宝、银行卡、信用卡、投资理财、其他，按类型分组展示并配品牌色（微信绿/支付宝蓝等），支持自定义图标和类型
- [x] **账户流水详情**：点击账户卡片弹出流水明细，展示该账户每一笔收支变动，支持分页滚动加载（每页20条），大数据量不卡顿
- [x] **账户余额变动审计**：每一次余额变动（收入/支出/转账/期初/手动调整）都自动记录流水，含变动前金额、变动额、变动后金额、操作人、时间，支持对账追溯
- [x] **并发安全**：使用 `SELECT ... FOR UPDATE` 行级锁 + 数据库事务，多账户按ID升序锁定防止死锁，并发记账不会出现余额错乱
- [x] **二级分类体系**：
    - 11个支出一级分类（餐饮/交通/购物/娱乐/居住/医疗/教育/旅行/宠物/人情/其他）
    - 7个收入一级分类（工资/奖金/投资收益/兼职外快/红包礼金/退款报销/其他收入）
    - 3个转账一级分类（账户转账/信用卡还款/充值提现）
    - 每个一级分类下 4-9 个预置二级分类，共 90+ 个常用分类
    - 支持手动添加自定义二级分类
- [x] **商家/备注关联**：记账时自动补全(datalist)，新商家名自动创建
- [x] **账单日历视图**：按月展示每日收支汇总，点击日期查看当天明细
- [x] **高级筛选**：类型、日期范围、一级/二级分类多维度筛选
- [x] **快捷日期**：本月/上月/本年/去年一键筛选
- [x] **借贷中心**：借出/借入记录、分期还款跟踪、结清标记、联系人管理
- [x] **借贷详情**：点击借贷卡片弹出详情，展示完整还款记录；还款支持添加备注说明
- [x] **借贷凭证图片**：新增/编辑借贷时可上传凭证图片，详情页支持全屏查看
- [x] **还款到期提醒**：借贷到期前3天及当天自动生成个人通知，逾期/即将到期借贷卡片红色/橙色醒目标记
- [x] **信用卡还款日**：信用卡账户可设置账单日和还款日，还款日前3天及当天自动提醒账本全体成员
- [x] **记一笔快捷加分类**：记账弹窗内可直接创建新分类，无需跳转设置页
- [x] **记账模板**：保存常用交易为模板，一键快速填充

### ✅ 1.2 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] **AI 健康饮食顾问**：基于账单餐饮消费数据，AI 分析饮食习惯并提供健康建议，支持多轮对话追问，对话历史自动保存

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

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

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

### ✅ 1.6 用户互动与运营
- [x] **系统通知公告**：管理员可发布系统更新/公告（通知/公告两种类型，支持立即发布或存为草稿），所有用户每个页面右上角显示铃铛🔔和未读数红点，点开查看公告列表与详情；阅读后自动标记已读，支持一键全部已读；60秒自动轮询刷新未读数；重要公告（系统升级/特殊通知）可勾选「弹窗公告」，用户进入应用时居中弹出确认对话框，确认后不再重复弹出
- [x] **个人通知中心**：铃铛弹窗内分「我的提醒」和「系统公告」两个 Tab，未读数合并显示；还款提醒（借贷到期/信用卡还款）由系统每天9:00自动检查生成，仅接收人本人可见；支持单条删除、全部已读、点击跳转到关联业务页面；PC端和移动端统一通知组件
- [x] **反馈中心**：用户可提交缺陷反馈/功能建议/其他反馈，支持填写联系方式；可查看自己的历史反馈及管理员回复，含待处理/处理中/已处理状态
- [x] **联系作者**：个人中心弹窗展示作者微信二维码、博客主页，方便用户交流反馈

### ✅ 1.7 PC 端桌面版
- [x] **独立 PC 布局**：侧边栏导航 + 顶栏布局，宽屏网格展示，与移动端 CSS/JS 完全隔离
- [x] **PC 首页**：月度收支卡片、预算进度、支出排行、最近记录、快捷入口
- [x] **PC 账单**：列表/日历双视图，日历默认选中当天并展示明细，高级筛选侧栏
- [x] **PC 账户**：账户卡片网格展示，信用卡到期醒目标记，流水明细分页
- [x] **PC 报表**：周/月/季/年切换，Canvas 饼图/折线图/柱状图，AI 智能分析
- [x] **PC 借贷**：借贷卡片网格，到期提醒标记，详情弹窗含还款时间轴
- [x] **PC 个人中心**：账本管理、AI 配置、反馈中心、公告管理、版本记录
- [x] **一键切换**：PC 端顶栏可一键切换到移动端视图，反之亦然
- [x] 访问 `/pc/` 路径进入 PC 端（如 `http://localhost:3000/pc/index.html`）

### ✅ 1.8 其他功能
- [x] 明/暗主题切换（LocalStorage持久化）
- [x] CSV 表格导出（UTF-8 BOM 支持Excel中文）
- [x] JSON 完整数据备份导出
- [x] H5 移动端响应式适配，支持iOS/Android
- [x] JWT 身份认证 + bcrypt 密码加密
- [x] 后端路由模块化，前端CSS/JS按页面拆分
- [x] 数据永久存储在你自己的服务器，API Key 仅保存在服务端
- [x] 新用户注册自动复制系统分类和默认账户
- [x] 接口限流防刷（登录/注册/AI/反馈/公告/通知等按接口独立限流）
- [x] 操作日志审计：关键写操作自动记录操作人、业务类型、时间
- [x] 定时任务：还款提醒每天9:00自动检查，服务重启自动补检（唯一索引去重）

## 🛠️ 2. 技术栈

- **后端**: Node.js + Express + MySQL (mysql2/connection pool)
- **前端**: 原生 HTML/CSS/JS（无框架依赖）
- **数据库**: MySQL 8.0+（支持5.7），主键使用雪花算法生成18位数字ID，逻辑删除（del_flag）
- **认证**: JWT + bcryptjs
- **AI**: 智谱 AI GLM-4-Flash（文本）/ GLM-4V-Flash（视觉OCR）
- **语音**: 浏览器原生 Web Speech API（中文）
    - 浏览器支持情况：
        - ✅ Chrome（桌面/Android）：完整支持，但**需要翻墙**才能使用（底层调用Google云端语音识别服务，国内被墙）
        - ✅ Edge：支持，使用微软Azure语音服务，**无需翻墙**
        - ⚠️ Safari（iOS 14.5+/macOS 11.3+）：部分支持，iOS需HTTPS，使用苹果自有服务无需翻墙
        - ⚠️ OPPO/vivo/小米/华为等国产手机自带浏览器：基于Chromium内核，API可能存在，但同样**需要翻墙**才能连接Google服务，实际效果取决于厂商是否在系统中保留该接口。测试经验： OPPO 浏览器上点一下麦克风按钮试试，能点动（没被隐藏）就说明 API 存在，翻墙后应该就能用。
        - ❌ Firefox：不支持
        - ❌ 微信内置浏览器：基本不支持
        - ⚠️ 其他国产浏览器（QQ/UC等）：基于Chromium内核的部分支持，大多数仍需翻墙
    - **注意事项**：
        - Web Speech API 要求 **HTTPS** 环境（localhost 开发环境除外）
        - Chrome 语音识别依赖 Google 云端服务，**国内无法直连，需要翻墙（VPN/代理）**，否则会报 network 错误
        - Edge 使用微软 Azure 语音服务，国内可直连，无需翻墙
        - Safari 使用苹果自有语音服务，不需要翻墙，但仅支持 iOS 14.5+/macOS 11.3+
        - 建议生产环境配置 SSL 证书通过 HTTPS 访问
- **图表**: 原生 Canvas 手写绘制（无Chart.js依赖）

## 3. 部署步骤

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

### 3.2 初始化数据库

根据你的安装情况选择对应的方式：

**情况一：全新安装（第一次部署系统）**

直接运行初始化脚本，一键创建数据库、表结构、默认分类和账户：
```bash
mysql -u root -p
```
```sql
source /你的路径/smart-ledger/server/sql/v2.0.x/init-db.sql;
```
这会自动创建 `smart_ledger` 数据库、所有表结构（主键雪花ID + del_flag逻辑删除），并初始化默认分类（90+个）和默认账户。

**情况二：从 v1.0.x 老版本升级**

请按日期顺序依次执行 `server/sql/v2.0.x/` 目录下所有以日期开头的增量迁移脚本（`init-db.sql` 不需要运行）：
```bash
mysql -u root -p smart_ledger
```
```sql
-- 严格按文件名日期顺序逐个执行，例如：
source /你的路径/smart-ledger/server/sql/v2.0.x/20260726-rename-tables-v2.sql;
source /你的路径/smart-ledger/server/sql/v2.0.x/20260727-remove-autoincrement-snowflake.sql;
source /你的路径/smart-ledger/server/sql/v2.0.x/20260727-add-del-flag-logic-delete.sql;
source /你的路径/smart-ledger/server/sql/v2.0.x/20260727-add-column-comments.sql;
-- ...后续新增的增量脚本继续按日期往后执行
```

> ⚠️ **升级注意事项**：
> - 脚本必须按文件名日期从小到大顺序执行，日期代表脚本生成顺序，跳过或乱序可能导致表结构异常
> - 执行前建议先备份旧数据库：`mysqldump -u root -p smart_ledger > backup.sql`
> - `init-db.sql` 仅用于全新安装，升级场景**不要**执行，否则会覆盖已有数据
> - 如果不确定自己的版本，先查看 `server/sql/` 目录下是否有 v1.0.x 旧版本脚本目录

**情况三：从 v2.0.1 升级到 v2.0.2**

1. 执行增量 SQL 脚本（新增饮食顾问字段、借贷凭证字段、版本记录）：
```sql
source /你的路径/smart-ledger/server/sql/v2.0.x/20260805-v2.0.2-update.sql;
```

2. 【重要】v2.0.2 起上传文件目录从 `public/uploads/` 改为根目录 `uploads/YYYY/MM/DD/`。升级后需执行迁移脚本，将历史附件移动到新目录并同步更新数据库中的图片路径：
```bash
cd server
node scripts/migrate-uploads.js
```
> 脚本会自动按文件修改日期归类到 `uploads/YYYY/MM/DD/`，并更新 `sl_biz_record.image_url` 和 `sl_biz_loan.image_url`。执行前建议备份 `public/uploads/` 目录。全新安装（无历史文件）可跳过此步。

**情况四：从 v2.0.2 升级到 v2.0.3**

1. 执行增量 SQL 脚本（新增个人通知表、信用卡账单日/还款日字段）：
```sql
source /你的路径/smart-ledger/server/sql/v2.0.x/20260805-v2.0.3-add-notifications.sql;
```
2. 重启服务即可，定时任务会在服务启动时自动执行一次检查，之后每天9:00自动生成还款提醒。

### 3.3 配置环境变量
服务通过 `.env` 文件读取配置，支持多环境分离：

| 文件 | 用途 | 加载条件 |
|------|------|----------|
| `.env.development` | 本地开发环境 | `NODE_ENV=development` |
| `.env.production` | 线上生产环境 | `NODE_ENV=production` |
| `.env` | 默认配置（可选） | 不设置 NODE_ENV 时 |

首次使用复制模板：
```bash
cd server
cp .env.template .env.development   # 本地开发
cp .env.template .env.production    # 线上生产
```

编辑对应 `.env` 文件，填入你的数据库和JWT配置：
```env
# 数据库配置
DB_HOST=localhost
DB_USER=root
DB_PASSWORD=your_mysql_password
DB_NAME=smart_ledger

# JWT密钥（生产环境务必用随机字符串，可用 node -e "console.log(require('crypto').randomBytes(48).toString('hex'))" 生成）
JWT_SECRET=your-super-secret-random-key-here

# 端口
PORT=3000

# 环境标记
NODE_ENV=development

# 允许的前端域名（CORS，多个用逗号分隔）
ALLOWED_ORIGINS=http://localhost:3000,https://yourdomain.com
```

> 也可以不创建 `.env` 文件，`db.js` 默认连接 `localhost/root/smartLan@2026/smart_ledger`（适合本地快速体验）。

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

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

### 3.5 安装依赖并启动服务
```bash
cd server
npm install
npm start
```

本地开发启动（自动加载 `.env.development`）：
```bash
# Windows
npm start
默认会读取 .env
或者指定环境启动
cmd /c "set NODE_ENV=development && npm start"
# Linux/Mac
NODE_ENV=development npm start
```

服务默认运行在 `http://localhost:3000`，直接在浏览器打开即可使用。
默认管理员账号：`admin` / `123456`（建议注册自己的账号）。

### 3.6 生产环境部署
使用 PM2 进行进程管理（自动加载 `.env.production`）：
```bash
npm install -g pm2
pm2 start server.js --name smart-ledger --env production
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;
    }
}
```

### 3.7 Git 分支管理

项目采用经典的三分支开发模型：

| 分支 | 作用 | 稳定性 | 使用场景 |
|------|------|--------|----------|
| `master` | 生产环境分支，对应线上运行的代码 | 稳定，经过测试 | 生产部署、线上热修复 |
| `develop` | 开发集成分支，所有功能开发完成后合入此处 | 相对稳定，偶尔有未验证代码 | 日常开发合并、测试环境部署 |
| `feature/*` | 功能开发分支，从 develop 切出，开发完成后合回 develop | 不稳定，正在开发中 | 具体功能开发、bug修复 |

**日常开发流程：**

```bash
# 1. 从 develop 切出功能分支
git checkout develop
git pull origin develop
git checkout -b feature/your-feature-name

# 2. 在 feature 分支上开发、提交代码
git add .
git commit -m "feat: 描述你的改动"

# 3. 开发完成后合回 develop
git checkout develop
git pull origin develop
git merge feature/your-feature-name
git push origin develop

# 4. 功能分支合并后可删除
git branch -d feature/your-feature-name
```

**版本发布流程：**

```bash
# 当 develop 上的功能足够稳定，准备发布时
git checkout master
git pull origin master
git merge develop                    # 将 develop 合并到 master
git tag v2.0.x                       # 打版本标签
git push origin master --tags
```

**各分支部署对应关系：**
- `master` → 生产环境（线上服务器 pm2 部署）
- `develop` → 测试/预发布环境
- `feature/*` → 本地开发环境

> 普通用户直接使用 `master` 分支即可，开发者参与贡献请基于 `develop` 切 `feature/*` 分支开发。

## 4. 使用方法速览

| 操作 | 方法 |
|------|------|
| 记一笔 | 点击右下角 + FAB |
| 语音记账 | 记账弹窗点 🎤 说一句话，或账单页快捷栏点 🎤 |
| AI文字记账 | 记账弹窗顶部AI框输入"打车25元"点解析，或账单页AI快捷栏 |
| 拍照识别小票 | 账单页AI快捷栏点 📷 拍照 |
| 查看日历 | 账单页点「📅日历」按钮 |
| 筛选账单 | 账单页点「🔍筛选」按钮，支持日期/分类筛选 |
| 查看报表 | 底部导航切到「报表」，选周报/月报/季报/年报 |
| AI分析报表 | 报表页点「🤖 AI智能分析」 |
| 切换账本 | 「我的」页面顶部下拉切换 |
| 邀请成员 | 「我的」→ 「成员管理」→ 邀请 |
| 导出数据 | 「我的」→ 「导出数据」|
| 深色模式 | 「我的」→ 切换深色模式开关 |
| 查看公告/提醒 | 每个页面右上角 🔔 铃铛，点开查看「我的提醒」和「系统公告」 |
| 还款提醒 | 借贷/信用卡到期前3天及当天自动收到通知，铃铛显示未读数 |
| 弹窗公告确认 | 重要通知（如系统升级）进入应用时自动弹出确认框，确认后不再弹出 |
| 切换PC/移动端 | PC端顶栏点「📱切换移动端」，移动端底部「我的」→「切换到PC端」 |
| 提交反馈 | 「我的」→ 「反馈中心」 |
| 联系作者 | 「我的」→ 「联系作者」（微信二维码 + 博客） |
| 发布公告 | 管理员在「我的」→ 「公告管理」发布/编辑/删除公告 |

## 5. 项目结构

```
smart-ledger/
├── server/                     # 后端代码
│   ├── server.js               # Express 服务入口（自动加载对应NODE_ENV的.env文件）
│   ├── db.js                   # MySQL 连接池配置（优先读环境变量）
│   ├── logger.js               # 日志记录模块（登录日志+操作日志）
│   ├── package.json
│   ├── .env.development        # 本地开发环境变量（DB/JWT/CORS等）
│   ├── .env.production         # 生产环境变量
│   ├── .env.template           # 环境变量模板
│   ├── sql/                    # 数据库脚本目录
│   │   ├── v2.0.x/
│   │   │   ├── init-db.sql     # 数据库初始化脚本（表结构+90+系统分类+默认配置）
│   │   │   └── *.sql           # 增量升级DDL脚本（按日期命名）
│   ├── utils/
│   │   ├── snowflake.js        # 雪花ID生成器（18位数字ID，不可枚举）
│   │   └── auditContext.js     # AsyncLocalStorage 透传当前用户ID（created_by/updated_by 自动写入）
│   ├── jobs/                   # 定时任务
│   │   └── reminderJob.js      # 还款提醒任务（每天9:00检查借贷/信用卡到期，自动生成通知）
│   ├── scripts/                # 运维/数据维护脚本（按需手动执行，不随服务启动）
│   │   ├── sync-categories.js  # 系统分类同步：为所有账本补齐缺失的系统分类
│   │   ├── dedupe-categories.js# 重复分类清理：合并同名分类、提升旧三级分类为二级
│   │   ├── migrate-uploads.js  # 历史附件迁移：public/uploads/ → uploads/YYYY/MM/DD/，同步更新数据库路径
│   │   └── reset-admin.js      # 重置 admin 用户密码为 123456（应急使用）
│   ├── middleware/
│   │   ├── auth.js             # JWT 认证 + 管理员权限（requireAdmin）中间件
│   │   └── bookAccess.js       # 账本成员权限校验（owner/editor/viewer）
│   ├── 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配置读写）
│   │   ├── notice.js           # 系统通知公告（用户查看/已读，管理员CRUD）
│   │   ├── notifications.js    # 个人通知（还款提醒列表/已读/删除，仅本人可见）
│   │   ├── feedback.js         # 用户反馈（提交/历史，管理员查看回复）
│   │   ├── version.js          # 系统版本记录
│   │   ├── upload.js           # 小票图片上传
│   │   └── export.js           # CSV/JSON 数据导出
│   └── uploads/                # 上传文件存储（按 YYYY/MM/DD 日期分目录，自动创建）
│
├── public/                     # H5 移动端前端（多页面架构）
│   ├── 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            # 借贷中心逻辑
│
└── pc/                         # PC 端桌面版前端（与移动端完全隔离）
    ├── index.html              # PC 首页
    ├── bills.html              # PC 账单页（列表+日历双视图）
    ├── accounts.html           # PC 账户管理页
    ├── reports.html            # PC 数据报表页
    ├── loans.html              # PC 借贷中心页
    ├── profile.html            # PC 个人中心页
    ├── css/
    │   ├── pc-layout.css       # PC 侧边栏+顶栏布局
    │   ├── pc-components.css   # PC 组件基础样式
    │   ├── pc-reports.css      # PC 报表页样式
    │   ├── pc-loans.css        # PC 借贷页样式
    │   └── pc-profile.css      # PC 个人中心样式
    └── js/
        ├── pc-common.js        # PC 公共逻辑（侧边栏/顶栏/通知徽章/主题）
        ├── pc-home.js          # PC 首页逻辑
        ├── pc-bills.js         # PC 账单逻辑（日历默认选中当天）
        ├── pc-accounts.js      # PC 账户逻辑（信用卡到期提醒）
        ├── pc-reports.js       # PC 报表逻辑（Canvas图表+AI分析）
        ├── pc-loans.js         # PC 借贷逻辑（到期标记/还款时间轴）
        ├── pc-profile.js       # PC 个人中心逻辑
        └── pc-addrecord.js     # PC 记账弹窗（独立版本）
```

## 6. API 接口文档

### 6.1 基础接口

| 接口 | 方法 | 说明 |
|------|------|------|
| `/api/auth/register` | POST | 用户注册（自动创建默认账本+分类+账户） |
| `/api/auth/login` | POST | 用户登录 |
| `/api/auth/me` | GET/PUT | 获取/更新用户信息 |
| `/api/auth/change-password` | POST | 修改密码（需验证原密码） |
| `/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/accounts/:id/balance` | PUT | 手动调整账户余额（自动记录adjust类型流水） |
| `/api/accounts/:id/transactions` | GET | 查询账户余额变动流水（支持日期范围筛选） |
| `/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` | PATCH/DELETE | 编辑借贷备注/凭证 / 删除借贷 |
| `/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 备份 |

### 6.2 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/ai/diet` | POST | AI健康饮食分析（基于餐饮消费记录），结果保存为 diet 类型历史 |
| `/api/ai/diet-chat` | POST | 饮食顾问多轮对话追问（基于已有会话上下文） |

### 6.3 配置接口

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

### 6.4 通知公告接口

| 接口 | 方法 | 说明 |
|------|------|------|
| `/api/notice/unread-count` | GET | 获取未读公告数及是否管理员（铃铛显示用） |
| `/api/notice/popup` | GET | 获取当前用户未读的弹窗公告（启动时检查，最多5条） |
| `/api/notice` | GET | 已发布公告分页列表（含当前用户已读状态） |
| `/api/notice/:id` | GET | 公告详情（仅已发布） |
| `/api/notice/:id/read` | POST | 标记单条公告已读（幂等） |
| `/api/notice/read-all` | POST | 全部标记已读 |
| `/api/notice/admin` | POST | 【管理员】创建公告 |
| `/api/notice/admin/list` | GET | 【管理员】公告列表（含草稿，分页） |
| `/api/notice/admin/:id` | GET/PUT/DELETE | 【管理员】详情/更新/逻辑删除 |

### 6.5 个人通知接口（还款提醒）

| 接口 | 方法 | 说明 |
|------|------|------|
| `/api/notifications` | GET | 个人通知列表（分页，仅本人可见） |
| `/api/notifications/unread-count` | GET | 未读通知数（铃铛徽章用） |
| `/api/notifications/:id/read` | POST | 标记单条通知已读 |
| `/api/notifications/read-all` | POST | 全部标记已读 |
| `/api/notifications/:id` | DELETE | 删除单条通知（逻辑删除） |

> 通知由系统定时任务每天9:00自动生成（借贷到期前3天/当天、信用卡还款日前3天/当天），无需手动调用。

### 6.6 用户反馈接口

| 接口 | 方法 | 说明 |
|------|------|------|
| `/api/feedback` | POST | 提交反馈（缺陷/建议/其他） |
| `/api/feedback` | GET | 获取当前用户的反馈历史及回复 |
| `/api/feedback/:id` | DELETE | 删除自己的反馈（逻辑删除） |
| `/api/feedback/admin/list` | GET | 【管理员】所有反馈列表（分页/按状态筛选） |
| `/api/feedback/admin/:id/reply` | PUT | 【管理员】回复反馈 |

## 7. 数据库表结构

| 表名 | 说明 |
|------|------|
| `sl_sys_user` | 用户账号（bcrypt加密密码） |
| `sl_ledger_book` | 账本（多账本支持） |
| `sl_ledger_book_member` | 账本成员（owner/editor/viewer 权限） |
| `sl_acc_account` | 资金账户（余额/类型/图标） |
| `sl_acc_transaction` | 账户余额变动流水（审计追溯/对账） |
| `sl_biz_category` | 分类（二级层级，支出/收入/转账） |
| `sl_biz_entity` | 商家/成员/项目 |
| `sl_biz_record` | 收支流水（核心交易记录） |
| `sl_biz_budget` | 月度预算（总预算+分类预算） |
| `sl_biz_loan` | 借贷记录（借出/借入，含凭证图片） |
| `sl_biz_loan_record` | 还款明细 |
| `sl_ai_analysis` | AI分析历史（含饮食顾问多轮对话消息） |
| `sl_sys_config` | 系统配置（AI Key/模型等键值对） |
| `sl_sys_notice` | 系统通知公告（标题/类型/内容/状态/是否弹窗，管理员发布） |
| `sl_sys_notice_read` | 公告用户阅读记录（per-user 已读状态，唯一键幂等） |
| `sl_sys_notification` | 个人通知（还款提醒等，仅接收人可见，含类型/关联业务/已读状态/去重唯一键） |
| `sl_sys_feedback` | 用户反馈（类型/内容/联系方式/管理员回复） |
| `sl_sys_login_log` | 登录日志 |
| `sl_sys_oper_log` | 操作日志 |
| `sl_sys_version` | 系统版本升级记录（「我的」页面展示） |

### 数据库设计规范
- **主键**：全部使用 `BIGINT UNSIGNED`，由应用层雪花算法生成18位数字ID，不再使用AUTO_INCREMENT自增，防止ID被枚举猜测
- **逻辑删除**：所有业务表包含 `del_flag TINYINT` 字段（0=正常，1=已删除），删除操作UPDATE而非DELETE，支持数据恢复与审计
- **日志表**：不设del_flag，永久保留审计记录

## 8. 数据安全

- 所有数据存储在你自己的服务器，不会上传到任何第三方
- AI API Key 仅保存在服务端数据库，前端接口返回时脱敏显示
- 密码使用 bcrypt 加密存储
- JWT token 有效期30天，生产环境密钥通过环境变量配置
- 所有API接口需要JWT认证，账本数据通过成员权限隔离
- **雪花算法ID**：主键使用18位数字雪花ID，不可被枚举猜测，防止ID遍历攻击
- **逻辑删除**：删除操作只标记 `del_flag=1`，不物理删除数据，支持数据恢复与历史追溯
- **IDOR防护**：所有通过ID操作的接口，都会校验资源所属账本与用户权限，防止通过猜测ID越权访问别人数据
- **跨账本引用校验**：记账时关联的账户/分类/商家，都会校验属于同一账本，防止跨账本数据污染
- **并发安全**：余额变更使用数据库事务 + `SELECT ... FOR UPDATE` 行级锁，多账户按ID升序锁定避免死锁，保证高并发下余额准确
- **余额变动审计**：每一次余额变动（新增/编辑/删除记录、转账、期初余额、手动调整）都记录完整流水，含变动前/变动额/变动后金额、操作人、时间，支持对账追溯
- **输入安全**：XSS防护（输出HTML转义）、文件上传MIME白名单（仅允许图片）、CSV导出防公式注入、登录接口限流
- 可自行配置 HTTPS 保证传输安全

## 9. 演示图

### 9.1 登录注册
![登录](files/00登录/0.png)
![注册](files/00登录/1.png)

### 9.2 首页
![首页概览](files/01首页/01.png)
![支出排行与最近记录](files/01首页/02.png)
![记账弹窗-支出](files/01首页/03.png)
![记账弹窗-收入](files/01首页/04.png)
![记账弹窗-转账](files/01首页/05.png)

### 9.3 账单
![账单列表](files/02账单/11.png)
![日历视图](files/02账单/12.png)
![高级筛选](files/02账单/13.png)

### 9.4 账户
![账户管理](files/03账户/31.png)
![新增账户](files/03账户/32.png)

### 9.5 报表
![分类饼图](files/04报表/41.png)
![支出排行与趋势图](files/04报表/42.png)
![异常检测与月底预测](files/04报表/43.png)
![AI智能分析报告](files/04报表/44.png)
![历史分析记录](files/04报表/45.png)

### 9.6 我的
![个人中心](files/05我的/51.png)
![账本切换](files/05我的/52.png)
![借贷中心](files/05我的/53.png)
![新增借贷](files/05我的/54.png)
![深色模式](files/05我的/55.png)
![邀请成员协同](files/05我的/56.png)
![修改密码](files/05我的/57.png)

## 10. 📞 联系方式
如有问题或建议，欢迎联系开发者
微信服务号名称：正在走向自律1
微信服务号ID：xiaobawang114AI

![微信公众号](files/qrcode_for_gh.jpg)

## 11. 📄 许可证
MIT License

## 12. 🤝 贡献
欢迎提交 Issue 和 Pull Request！