💰 BillAI - 智能账单分析系统

一个基于微服务架构的个人账单分析工具，支持微信和支付宝账单的自动解析、智能分类和可视化分析。

变更记录见 CHANGELOG.md。

✨ 功能特性

• 📊 账单分析 - 自动解析微信/支付宝账单，生成可视化报表
• 🏷️ 智能分类 - 基于关键词匹配的交易分类推断
• 📈 趋势图表 - 日/月消费趋势、分类排行、收支对比
• 🔍 复核修正 - 对不确定的分类进行人工复核
• 💾 数据持久化 - MongoDB 存储原始数据和清洗后数据，支持去重检查
• 🐳 一键部署 - Docker Compose 快速启动全部服务
• <EFBFBD> 用户认证 - JWT Token 登录认证

🏗️ 系统架构

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

数据流

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
│
├── mock_data/                # 测试数据目录
├── mongodata/                # MongoDB 数据持久化
└── docker-compose.yaml       # 容器编排

🚀 快速开始

环境要求

• Docker & Docker Compose
• (可选) Go 1.21+、Python 3.12+、Node.js 20+

一键启动

# 克隆项目
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	数据库管理

💻 本地开发

前端开发

cd web
yarn install
yarn dev

后端开发

cd server
go mod download
go run .

分析服务开发

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)

🛣️ 路线图

• 添加用户认证 (JWT)
• 手动录入账单
• 数据分析图表
• 支持更多账单格式（银行账单）
• AI 智能分类（LLM）
• 预算管理功能
• 移动端适配
• 数据导出 (Excel/PDF)

📋 版本历史

版本	日期	主要更新
v1.0.9	2026-01-19	🗑️ 移除 Webhook 自动部署功能
v1.0.8	2026-01-18	♻️ 前端账单模型统一为 UIBill、新增账单详情弹窗组件
v1.0.7	2026-01-16	🔐 Token 过期由后端统一判断、401 自动退登
v1.0.6	2026-01-08	🐛 修复数据分析页面总支出和大盘数据错误
v1.0.5	2026-01-08	🐛 修复支付宝时间格式解析错误
v1.0.4	2026-01-13	✨ MongoDB 数据持久化、上传去重
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

🤝 贡献指南

欢迎提交 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 文件

🙏 致谢

• SvelteKit
• Gin
• FastAPI
• shadcn-svelte