# 💰 BillAI - 智能账单分析系统

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

![版本](https://img.shields.io/badge/版本-1.0.6-green)
![架构](https://img.shields.io/badge/架构-微服务-blue)
![Go](https://img.shields.io/badge/Go-1.21-00ADD8)
![Python](https://img.shields.io/badge/Python-3.12-3776AB)
![Svelte](https://img.shields.io/badge/SvelteKit-5-FF3E00)
![MongoDB](https://img.shields.io/badge/MongoDB-8.0-47A248)
![Docker](https://img.shields.io/badge/Docker-Compose-2496ED)

## ✨ 功能特性

- 📊 **账单分析** - 自动解析微信/支付宝账单，生成可视化报表
- 🏷️ **智能分类** - 基于关键词匹配的交易分类推断
- 📈 **趋势图表** - 日/月消费趋势、分类排行、收支对比
- 🔍 **复核修正** - 对不确定的分类进行人工复核
- 💾 **数据持久化** - 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.7** | 2026-01-16 | 🔐 Token 过期由后端统一判断、401 自动退登；后端数据访问层收敛 |
| **v1.0.6** | 2026-01-08 | 🐛 修复数据分析页面总支出和大盘数据错误 |
| **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/)