150 lines
3.3 KiB
Markdown
150 lines
3.3 KiB
Markdown
# Finance Bot
|
|
|
|
Telegram bot for family finance management built with Python 3.12, aiogram, FastAPI, and PostgreSQL.
|
|
|
|
## Features
|
|
|
|
- 👨👩👧👦 Family group management
|
|
- 💰 Income/expense tracking
|
|
- 💳 Multiple accounts (wallets)
|
|
- 📊 Analytics and reports
|
|
- 🎯 Savings goals
|
|
- 💵 Budget management
|
|
- 📱 Telegram bot interface
|
|
- ⚡ FastAPI REST API (optional)
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
finance_bot/
|
|
├── app/
|
|
│ ├── bot/ # Telegram bot handlers
|
|
│ │ ├── handlers/ # Command handlers
|
|
│ │ ├── keyboards/ # Keyboard layouts
|
|
│ │ └── services/ # Bot services
|
|
│ ├── core/ # Core configuration
|
|
│ ├── db/ # Database models & repositories
|
|
│ │ ├── models/ # SQLAlchemy models
|
|
│ │ └── repositories/ # Data access layer
|
|
│ ├── schemas/ # Pydantic schemas
|
|
│ ├── services/ # Business logic
|
|
│ │ ├── finance/ # Finance operations
|
|
│ │ ├── analytics/ # Analytics reports
|
|
│ │ └── notifications/ # Notifications
|
|
│ └── main.py # Application entry point
|
|
├── migrations/ # Alembic migrations
|
|
├── requirements.txt # Python dependencies
|
|
├── docker-compose.yml # Docker services
|
|
├── Dockerfile # Docker image
|
|
└── .env.example # Environment template
|
|
```
|
|
|
|
## Quick Start
|
|
|
|
### 1. Clone and Setup
|
|
|
|
```bash
|
|
git clone <repo>
|
|
cd finance_bot
|
|
python -m venv .venv
|
|
source .venv/bin/activate
|
|
pip install -r requirements.txt
|
|
```
|
|
|
|
### 2. Configure Environment
|
|
|
|
```bash
|
|
cp .env.example .env
|
|
# Edit .env with your bot token and database settings
|
|
```
|
|
|
|
### 3. Using Docker Compose (Recommended)
|
|
|
|
```bash
|
|
docker-compose up -d
|
|
```
|
|
|
|
This will start:
|
|
- PostgreSQL database
|
|
- Redis cache
|
|
- Telegram bot
|
|
- FastAPI web server
|
|
|
|
### 4. Manual Setup (Without Docker)
|
|
|
|
```bash
|
|
# Install PostgreSQL and Redis locally
|
|
|
|
# Create database
|
|
createdb finance_db
|
|
|
|
# Run migrations
|
|
alembic upgrade head
|
|
|
|
# Run bot
|
|
python -m app.main
|
|
```
|
|
|
|
## Configuration
|
|
|
|
Edit `.env` file:
|
|
|
|
```
|
|
BOT_TOKEN=your_bot_token_here
|
|
DATABASE_URL=postgresql+psycopg2://user:pass@localhost:5432/finance_db
|
|
REDIS_URL=redis://localhost:6379/0
|
|
APP_ENV=development
|
|
```
|
|
|
|
## Development
|
|
|
|
### Database Migrations
|
|
|
|
```bash
|
|
# Create new migration
|
|
alembic revision --autogenerate -m "description"
|
|
|
|
# Apply migrations
|
|
alembic upgrade head
|
|
|
|
# Rollback last migration
|
|
alembic downgrade -1
|
|
```
|
|
|
|
### Code Style
|
|
|
|
```bash
|
|
# Format code
|
|
black app/
|
|
|
|
# Check linting
|
|
pylint app/
|
|
|
|
# Run tests
|
|
pytest tests/
|
|
```
|
|
|
|
## Architecture
|
|
|
|
- **Clean Architecture**: Separated domains, services, repositories
|
|
- **SQLAlchemy ORM**: Database models and relationships
|
|
- **Pydantic Validation**: Type-safe schemas
|
|
- **Repository Pattern**: Data access abstraction
|
|
- **Service Layer**: Business logic separation
|
|
- **aiogram 3.x**: Modern async Telegram bot framework
|
|
|
|
## Next Steps
|
|
|
|
1. ✅ Initialize project structure
|
|
2. ⬜ Complete database models and repositories
|
|
3. ⬜ Implement transaction handlers
|
|
4. ⬜ Add budget and goal management
|
|
5. ⬜ Create analytics reports
|
|
6. ⬜ Build notification system
|
|
7. ⬜ Add FastAPI REST endpoints
|
|
8. ⬜ Deploy to production
|
|
|
|
---
|
|
|
|
**Created**: December 10, 2025
|