feat: 完善项目架构并增强分析页面功能

- 新增项目文档和 Docker 配置 - 添加 README.md 和 TODO.md 项目文档 - 为各服务添加 Dockerfile 和 docker-compose 配置 - 重构后端架构 - 新增 adapter 层（HTTP/Python 适配器） - 新增 repository 层（数据访问抽象） - 新增 router 模块统一管理路由 - 新增账单处理 handler - 扩展前端 UI 组件库 - 新增 Calendar、DateRangePicker、Drawer、Popover 等组件 - 集成 shadcn-svelte 组件库 - 增强分析页面功能 - 添加时间范围筛选器（支持本月默认值） - 修复 DateRangePicker 默认值显示问题 - 优化数据获取和展示逻辑 - 完善分析器服务 - 新增 FastAPI 服务接口 - 改进账单清理器实现
2026-01-10 01:15:52 +08:00
parent 94f8ea12e6
commit 087ae027cc
96 changed files with 4301 additions and 482 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,265 @@
+# 💰 BillAI - 智能账单分析系统
+
+一个基于微服务架构的个人账单分析工具，支持微信和支付宝账单的自动解析、智能分类和可视化分析。
+
+![架构](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)
+
+## ✨ 功能特性
+
+- 📊 **账单分析** - 自动解析微信/支付宝账单，生成可视化报表
+- 🏷️ **智能分类** - 基于关键词匹配的交易分类推断
+- 📈 **趋势图表** - 日/月消费趋势、分类排行、收支对比
+- 🔍 **复核修正** - 对不确定的分类进行人工复核
+- 🐳 **一键部署** - Docker Compose 快速启动全部服务
+
+## 🏗️ 系统架构
+
+```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->>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/           # 页面路由
+│   │   │   ├── analysis/     # 📊 账单分析页
+│   │   │   ├── bills/        # 📋 账单列表页
+│   │   │   └── review/       # ✅ 复核页面
+│   │   └── lib/
+│   │       ├── components/   # UI 组件
+│   │       └── 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
+│
+├── 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/upload` | 上传并分析账单 |
+| `GET` | `/api/review` | 获取待复核记录 |
+| `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` | 数据库名称 |
+
+### 配置文件
+
+- `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)
+
+## 🤝 贡献指南
+
+欢迎提交 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/)