305 lines
9.1 KiB
Markdown
305 lines
9.1 KiB
Markdown
# 💰 BillAI - 智能账单分析系统
|
||
|
||
一个基于微服务架构的个人账单分析工具，支持微信和支付宝账单的自动解析、智能分类和可视化分析。
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
## ✨ 功能特性
|
||
|
||
- 📊 **账单分析** - 自动解析微信/支付宝账单，生成可视化报表
|
||
- 🏷️ **智能分类** - 基于关键词匹配的交易分类推断
|
||
- 📈 **趋势图表** - 日/月消费趋势、分类排行、收支对比
|
||
- 🔍 **复核修正** - 对不确定的分类进行人工复核
|
||
- 💾 **数据持久化** - MongoDB 存储原始数据和清洗后数据，支持去重检查
|
||
- 🐳 **一键部署** - Docker Compose 快速启动全部服务
|
||
- 🚀 **自动部署** - Gitea Webhook 触发零停机热更新
|
||
|
||
## 🏗️ 系统架构
|
||
|
||
```mermaid
|
||
graph TB
|
||
subgraph 用户层
|
||
User[👤 用户]
|
||
end
|
||
|
||
subgraph 前端服务
|
||
Web[🌐 Web 前端<br/>SvelteKit :3000]
|
||
end
|
||
|
||
subgraph 后端服务
|
||
Server[⚙️ Go 后端<br/>Gin :8080]
|
||
Analyzer[🐍 Python 分析服务<br/>FastAPI :8001]
|
||
end
|
||
|
||
subgraph 数据层
|
||
MongoDB[(🍃 MongoDB<br/>:27017)]
|
||
MongoExpress[📊 Mongo Express<br/>:8083]
|
||
end
|
||
|
||
User -->|访问| Web
|
||
Web -->|HTTP API| Server
|
||
Server -->|HTTP 调用| Analyzer
|
||
Server -->|读写数据| MongoDB
|
||
MongoExpress -->|管理| MongoDB
|
||
|
||
style Web fill:#ff3e00,color:#fff
|
||
style Server fill:#00ADD8,color:#fff
|
||
style Analyzer fill:#3776AB,color:#fff
|
||
style MongoDB fill:#47A248,color:#fff
|
||
```
|
||
|
||
### 数据流
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant U as 👤 用户
|
||
participant W as 🌐 Web
|
||
participant S as ⚙️ Server
|
||
participant A as 🐍 Analyzer
|
||
participant D as 🍃 MongoDB
|
||
|
||
rect rgb(240, 248, 255)
|
||
Note over U,D: 上传账单流程
|
||
U->>W: 上传账单文件
|
||
W->>S: POST /api/upload
|
||
S->>D: 去重检查（原始数据集合）
|
||
D-->>S: 重复记录数
|
||
S->>A: POST /clean (清洗账单)
|
||
A-->>S: 清洗结果 + 分类
|
||
S->>D: 存储原始数据 + 清洗后数据
|
||
D-->>S: 保存成功
|
||
S-->>W: 返回分析结果
|
||
W-->>U: 显示分析报表
|
||
end
|
||
|
||
rect rgb(255, 248, 240)
|
||
Note over U,D: 复核修正流程
|
||
U->>W: 查看待复核记录
|
||
W->>S: GET /api/review
|
||
S->>D: 查询不确定分类
|
||
D-->>S: 返回记录列表
|
||
S-->>W: 待复核数据
|
||
W-->>U: 显示复核界面
|
||
U->>W: 修正分类
|
||
W->>S: 更新分类
|
||
S->>D: 更新记录
|
||
end
|
||
```
|
||
|
||
## 📁 项目结构
|
||
|
||
```
|
||
BillAI/
|
||
├── web/ # 前端 (SvelteKit + TailwindCSS)
|
||
│ ├── src/
|
||
│ │ ├── routes/ # 页面路由
|
||
│ │ │ ├── login/ # 🔐 登录页面
|
||
│ │ │ ├── analysis/ # 📊 账单分析页
|
||
│ │ │ ├── bills/ # 📋 账单列表页
|
||
│ │ │ └── review/ # ✅ 复核页面
|
||
│ │ └── lib/
|
||
│ │ ├── components/ # UI 组件
|
||
│ │ ├── stores/ # 状态管理
|
||
│ │ └── services/ # API 服务
|
||
│ └── Dockerfile
|
||
│
|
||
├── server/ # 后端 (Go + Gin)
|
||
│ ├── adapter/ # 适配器层
|
||
│ │ ├── http/ # HTTP 客户端
|
||
│ │ └── python/ # 子进程调用
|
||
│ ├── handler/ # HTTP 处理器
|
||
│ ├── service/ # 业务逻辑
|
||
│ ├── repository/ # 数据访问层
|
||
│ └── Dockerfile
|
||
│
|
||
├── analyzer/ # 分析服务 (Python + FastAPI)
|
||
│ ├── server.py # FastAPI 入口
|
||
│ ├── clean_bill.py # 账单清洗
|
||
│ ├── category.py # 分类推断
|
||
│ ├── cleaners/ # 清洗器
|
||
│ │ ├── alipay.py # 支付宝
|
||
│ │ └── wechat.py # 微信
|
||
│ └── Dockerfile
|
||
│
|
||
├── webhook/ # Webhook 服务 (Go)
|
||
│ ├── main.go # Webhook 入口
|
||
│ └── Dockerfile
|
||
│
|
||
├── deploy.sh # 自动部署脚本
|
||
├── data/ # 测试数据目录
|
||
├── mongo/ # MongoDB 数据
|
||
└── docker-compose.yaml # 容器编排
|
||
```
|
||
|
||
## 🚀 快速开始
|
||
|
||
### 环境要求
|
||
|
||
- Docker & Docker Compose
|
||
- (可选) Go 1.21+、Python 3.12+、Node.js 20+
|
||
|
||
### 一键启动
|
||
|
||
```bash
|
||
# 克隆项目
|
||
git clone https://github.com/your-username/BillAI.git
|
||
cd BillAI
|
||
|
||
# 启动所有服务
|
||
docker-compose up -d --build
|
||
|
||
# 查看服务状态
|
||
docker-compose ps
|
||
```
|
||
|
||
### 访问地址
|
||
|
||
| 服务 | 地址 | 说明 |
|
||
|------|------|------|
|
||
| **前端页面** | http://localhost:3000 | Web 界面 |
|
||
| **后端 API** | http://localhost:8080 | RESTful API |
|
||
| **分析服务** | http://localhost:8001 | Python API |
|
||
| **Mongo Express** | http://localhost:8083 | 数据库管理 |
|
||
|
||
## 💻 本地开发
|
||
|
||
### 前端开发
|
||
|
||
```bash
|
||
cd web
|
||
yarn install
|
||
yarn dev
|
||
```
|
||
|
||
### 后端开发
|
||
|
||
```bash
|
||
cd server
|
||
go mod download
|
||
go run .
|
||
```
|
||
|
||
### 分析服务开发
|
||
|
||
```bash
|
||
cd analyzer
|
||
python -m venv venv
|
||
source venv/bin/activate # Windows: venv\Scripts\activate
|
||
pip install -r requirements.txt
|
||
python server.py
|
||
```
|
||
|
||
## 📖 API 文档
|
||
|
||
### 后端 API (Go)
|
||
|
||
| 方法 | 路径 | 说明 |
|
||
|------|------|------|
|
||
| `POST` | `/api/auth/login` | 用户登录 |
|
||
| `GET` | `/api/auth/validate` | 验证 Token |
|
||
| `POST` | `/api/upload` | 上传并分析账单 |
|
||
| `GET` | `/api/bills` | 查询账单列表 |
|
||
| `POST` | `/api/bills/manual` | 手动录入账单 |
|
||
| `GET` | `/api/review` | 获取待复核记录 |
|
||
| `GET` | `/api/review-stats` | 待复核统计 |
|
||
| `GET` | `/api/monthly-stats` | 月度统计 |
|
||
| `GET` | `/health` | 健康检查 |
|
||
|
||
### 分析服务 API (Python)
|
||
|
||
| 方法 | 路径 | 说明 |
|
||
|------|------|------|
|
||
| `POST` | `/clean` | 清洗账单文件 |
|
||
| `POST` | `/category/infer` | 推断交易分类 |
|
||
| `GET` | `/category/list` | 获取分类列表 |
|
||
| `POST` | `/detect` | 检测账单类型 |
|
||
| `GET` | `/health` | 健康检查 |
|
||
|
||
## ⚙️ 配置说明
|
||
|
||
### 环境变量
|
||
|
||
| 变量 | 默认值 | 说明 |
|
||
|------|--------|------|
|
||
| `ANALYZER_URL` | `http://localhost:8001` | Python 分析服务地址 |
|
||
| `ANALYZER_MODE` | `http` | 适配器模式: http/subprocess |
|
||
| `MONGO_URI` | `mongodb://localhost:27017` | MongoDB 连接 URI |
|
||
| `MONGO_DATABASE` | `billai` | 数据库名称 |
|
||
| `MONGO_RAW_COLLECTION` | `bills_raw` | 原始数据集合名称 |
|
||
| `MONGO_CLEANED_COLLECTION` | `bills_cleaned` | 清洗后数据集合名称 |
|
||
| `JWT_SECRET` | - | JWT 加密密钥 |
|
||
| `TOKEN_EXPIRY` | `24` | Token 过期时间（小时） |
|
||
| `ADMIN_USERNAME` | - | 管理员用户名（可选） |
|
||
| `ADMIN_PASSWORD` | - | 管理员密码（可选） |
|
||
|
||
### 配置文件
|
||
|
||
- `server/config.yaml` - Go 后端配置
|
||
- `analyzer/config/category.yaml` - 分类规则配置
|
||
|
||
## 🔧 技术栈
|
||
|
||
| 层级 | 技术 | 版本 |
|
||
|------|------|------|
|
||
| **前端** | SvelteKit + TailwindCSS | 5.x / 4.x |
|
||
| **后端** | Go + Gin | 1.21 / 1.9 |
|
||
| **分析服务** | Python + FastAPI | 3.12 / 0.109+ |
|
||
| **数据库** | MongoDB | 8.0 |
|
||
| **容器化** | Docker Compose | - |
|
||
|
||
## 📊 支持的账单格式
|
||
|
||
- ✅ **微信支付** - 微信支付账单流水文件 (CSV)
|
||
- ✅ **支付宝** - 支付宝交易明细 (CSV)
|
||
|
||
## 🛣️ 路线图
|
||
|
||
- [x] 添加用户认证 (JWT)
|
||
- [x] 手动录入账单
|
||
- [x] 数据分析图表
|
||
- [ ] 支持更多账单格式（银行账单）
|
||
- [ ] AI 智能分类（LLM）
|
||
- [ ] 预算管理功能
|
||
- [ ] 移动端适配
|
||
- [ ] 数据导出 (Excel/PDF)
|
||
|
||
## 📋 版本历史
|
||
|
||
| 版本 | 日期 | 主要更新 |
|
||
|------|------|----------|
|
||
| **v1.0.5** | 2026-01-08 | 🐛 修复支付宝时间格式解析错误，修复WebHook编译错误 |
|
||
| **v1.0.4** | 2026-01-13 | 🚀 Gitea Webhook 自动部署、零停机热更新 |
|
||
| **v1.0.3** | 2026-01-13 | ✨ DateTimePicker 组件、收支分类动态切换 |
|
||
| **v1.0.2** | 2026-01-11 | 🐛 修复时区和金额解析问题 |
|
||
| **v1.0.1** | 2026-01-11 | 🐛 修复复核页面显示错误 |
|
||
| **v1.0.0** | 2026-01-07 | 🎉 初始版本发布 |
|
||
|
||
详细更新日志请查看 [CHANGELOG.md](CHANGELOG.md)
|
||
|
||
## 🤝 贡献指南
|
||
|
||
欢迎提交 Issue 和 Pull Request！
|
||
|
||
1. Fork 本仓库
|
||
2. 创建特性分支 (`git checkout -b feature/amazing-feature`)
|
||
3. 提交更改 (`git commit -m 'Add amazing feature'`)
|
||
4. 推送分支 (`git push origin feature/amazing-feature`)
|
||
5. 创建 Pull Request
|
||
|
||
## 📄 许可证
|
||
|
||
本项目采用 MIT 许可证 - 详见 [LICENSE](LICENSE) 文件
|
||
|
||
## 🙏 致谢
|
||
|
||
- [SvelteKit](https://kit.svelte.dev/)
|
||
- [Gin](https://gin-gonic.com/)
|
||
- [FastAPI](https://fastapi.tiangolo.com/)
|
||
- [shadcn-svelte](https://shadcn-svelte.com/)
|