init commit
This commit is contained in:
245
DEVELOPMENT.md
Normal file
245
DEVELOPMENT.md
Normal file
@@ -0,0 +1,245 @@
|
||||
## 🚀 ЭТАП 1: ИНИЦИАЛИЗАЦИЯ ПРОЕКТА — ЗАВЕРШЕНО ✅
|
||||
|
||||
**Дата**: 10 декабря 2025
|
||||
**Статус**: Основная архитектура готова к использованию
|
||||
|
||||
---
|
||||
|
||||
## 📦 ЧТО СОЗДАНО
|
||||
|
||||
### 1️⃣ **Структура проекта**
|
||||
```
|
||||
finance_bot/
|
||||
├── app/
|
||||
│ ├── bot/ ✅ Telegram bot handlers, keyboards
|
||||
│ ├── core/ ✅ Configuration management
|
||||
│ ├── db/ ✅ Models, repositories, database setup
|
||||
│ ├── schemas/ ✅ Pydantic validation schemas
|
||||
│ ├── services/ ✅ Business logic layer
|
||||
│ │ ├── finance/ - TransactionService, BudgetService, GoalService, AccountService
|
||||
│ │ ├── analytics/ - ReportService
|
||||
│ │ └── notifications/ - NotificationService
|
||||
│ ├── api/ ✅ FastAPI application
|
||||
│ └── main.py ✅ Bot entry point
|
||||
├── migrations/ ✅ Alembic database migrations
|
||||
├── Dockerfile ✅ Container image
|
||||
├── docker-compose.yml ✅ Multi-service orchestration
|
||||
├── requirements.txt ✅ Python dependencies
|
||||
├── alembic.ini ✅ Migration config
|
||||
├── .env ✅ Environment variables
|
||||
└── README.md ✅ Documentation
|
||||
```
|
||||
|
||||
### 2️⃣ **Database Models** (8 таблиц + relationships)
|
||||
- ✅ **User** - Telegram users
|
||||
- ✅ **Family** - Family groups with roles and settings
|
||||
- ✅ **FamilyMember** - Group membership tracking
|
||||
- ✅ **FamilyInvite** - Invitation management
|
||||
- ✅ **Account** - Wallets/accounts (card, cash, deposits)
|
||||
- ✅ **Category** - Income/expense categories with emoji
|
||||
- ✅ **Transaction** - Income/expense/transfer records
|
||||
- ✅ **Budget** - Budget tracking per category
|
||||
- ✅ **Goal** - Savings goals with progress
|
||||
|
||||
### 3️⃣ **Services & Business Logic**
|
||||
- ✅ **TransactionService** - Create, track, and delete transactions
|
||||
- ✅ **AccountService** - Manage accounts and transfers
|
||||
- ✅ **BudgetService** - Budget tracking and alerts
|
||||
- ✅ **GoalService** - Savings goals and progress
|
||||
- ✅ **ReportService** - Analytics by category, user, period
|
||||
- ✅ **NotificationService** - Message formatting
|
||||
|
||||
### 4️⃣ **Database Access Layer**
|
||||
- ✅ **BaseRepository** - Generic CRUD operations
|
||||
- ✅ **UserRepository** - User queries
|
||||
- ✅ **FamilyRepository** - Family and member management
|
||||
- ✅ **AccountRepository** - Account operations
|
||||
- ✅ **CategoryRepository** - Category filtering
|
||||
- ✅ **TransactionRepository** - Complex transaction queries
|
||||
- ✅ **BudgetRepository** - Budget management
|
||||
- ✅ **GoalRepository** - Goal tracking
|
||||
|
||||
### 5️⃣ **Telegram Bot**
|
||||
- ✅ Start handler with welcome message
|
||||
- ✅ Main menu keyboard
|
||||
- ✅ Transaction type selection
|
||||
- ✅ Placeholder handlers for: user, family, transaction
|
||||
- ✅ Async event loop ready
|
||||
|
||||
### 6️⃣ **API (FastAPI)**
|
||||
- ✅ Health check endpoint
|
||||
- ✅ Auto API docs at /docs
|
||||
- ✅ CORS middleware configured
|
||||
- ✅ Ready for additional endpoints
|
||||
|
||||
### 7️⃣ **DevOps**
|
||||
- ✅ Docker Compose with 5 services (postgres, redis, bot, web, migrations)
|
||||
- ✅ Database health checks
|
||||
- ✅ Service dependencies
|
||||
- ✅ Volume persistence
|
||||
- ✅ Network isolation
|
||||
|
||||
### 8️⃣ **Migrations**
|
||||
- ✅ Alembic configured
|
||||
- ✅ Initial migration (001_initial.py) with all tables
|
||||
- ✅ Proper enum types for PostgreSQL
|
||||
- ✅ Indexes on frequently queried columns
|
||||
|
||||
---
|
||||
|
||||
## 🛠️ КАК ИСПОЛЬЗОВАТЬ
|
||||
|
||||
### **Вариант 1: Docker (РЕКОМЕНДУЕТСЯ)**
|
||||
```bash
|
||||
# Запустить все сервисы
|
||||
docker-compose up -d
|
||||
|
||||
# Проверить статус
|
||||
docker-compose ps
|
||||
|
||||
# Просмотреть логи бота
|
||||
docker-compose logs -f bot
|
||||
|
||||
# Остановить
|
||||
docker-compose down
|
||||
```
|
||||
|
||||
### **Вариант 2: Локальная разработка**
|
||||
```bash
|
||||
# 1. Установить PostgreSQL и Redis локально
|
||||
|
||||
# 2. Активировать окружение
|
||||
source .venv/bin/activate
|
||||
|
||||
# 3. Обновить .env
|
||||
vim .env
|
||||
|
||||
# 4. Запустить миграции
|
||||
alembic upgrade head
|
||||
|
||||
# 5. Запустить бот
|
||||
python -m app.main
|
||||
|
||||
# 6. В другом терминале - FastAPI
|
||||
uvicorn app.api.main:app --reload
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📋 СЛЕДУЮЩИЕ ШАГИ
|
||||
|
||||
### **Phase 2: Реализация основных команд**
|
||||
- [ ] `/register` - Регистрация пользователя
|
||||
- [ ] `/create_family` - Создание семейной группы
|
||||
- [ ] `/join_family <code>` - Присоединение к семье
|
||||
- [ ] `/add_account` - Добавление счета
|
||||
- [ ] `/add_transaction` - Запись расхода/дохода
|
||||
- [ ] `/balance` - Просмотр балансов
|
||||
- [ ] `/stats` - Аналитика за период
|
||||
|
||||
### **Phase 3: Интеграции**
|
||||
- [ ] Фото чеков (загрузка и сохранение)
|
||||
- [ ] Уведомления в группу при операциях
|
||||
- [ ] Повторяющиеся операции (автоматизм)
|
||||
- [ ] Export CSV/Excel
|
||||
|
||||
### **Phase 4: Расширенные функции**
|
||||
- [ ] Интеграция с банками (API)
|
||||
- [ ] OCR для распознавания чеков
|
||||
- [ ] Machine Learning для категоризации
|
||||
- [ ] Multiplayer режим
|
||||
- [ ] Webhook уведомления
|
||||
|
||||
---
|
||||
|
||||
## 🔧 КОНФИГУРАЦИЯ
|
||||
|
||||
### **.env переменные**
|
||||
```bash
|
||||
BOT_TOKEN=<твой_токен_от_BotFather>
|
||||
DATABASE_URL=postgresql+psycopg2://user:pass@localhost:5432/finance_db
|
||||
REDIS_URL=redis://localhost:6379/0
|
||||
APP_ENV=development
|
||||
```
|
||||
|
||||
### **Получить BOT_TOKEN**
|
||||
1. Открыть Telegram → @BotFather
|
||||
2. `/newbot` → заполнить детали
|
||||
3. Скопировать токен в .env
|
||||
|
||||
---
|
||||
|
||||
## 📊 АРХИТЕКТУРА
|
||||
|
||||
```
|
||||
USER (Telegram)
|
||||
↓
|
||||
TELEGRAM BOT (aiogram)
|
||||
↓
|
||||
HANDLERS (Commands, Messages)
|
||||
↓
|
||||
SERVICES (Business Logic)
|
||||
↓
|
||||
REPOSITORIES (Data Access)
|
||||
↓
|
||||
DATABASE (PostgreSQL)
|
||||
↓
|
||||
CACHE (Redis) [Optional]
|
||||
```
|
||||
|
||||
**Каждый слой изолирован** → легко тестировать и масштабировать
|
||||
|
||||
---
|
||||
|
||||
## 🧪 ТЕСТИРОВАНИЕ
|
||||
|
||||
```bash
|
||||
# Проверка синтаксиса
|
||||
python -m py_compile app/**/*.py
|
||||
|
||||
# Запуск тестов (если есть)
|
||||
pytest tests/
|
||||
|
||||
# Проверка импортов
|
||||
python -c "from app.main import main; print('OK')"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔐 БЕЗОПАСНОСТЬ
|
||||
|
||||
- ❌ **Не логируем токены** → check logs
|
||||
- ✅ **SQL injection защита** → SQLAlchemy ORM
|
||||
- ✅ **Validation** → Pydantic schemas
|
||||
- ✅ **Environment variables** → не в коде
|
||||
- ✅ **Role-based access** → Family roles
|
||||
|
||||
---
|
||||
|
||||
## 📝 NOTES FOR NEXT DEVELOPER
|
||||
|
||||
1. **Все модели** расширяемы — добавляй поля в `app/db/models/`
|
||||
2. **Создай миграцию** после изменения моделей:
|
||||
```bash
|
||||
alembic revision --autogenerate -m "description"
|
||||
```
|
||||
3. **Используй repositories** — никогда не пиши raw SQL
|
||||
4. **Тестируй репозитории** перед использованием в service'ах
|
||||
5. **Типизируй всё** — используй `typing` модуль
|
||||
|
||||
---
|
||||
|
||||
## 🎯 QUALITY CHECKLIST
|
||||
|
||||
- ✅ Типизированный код
|
||||
- ✅ Чистая архитектура
|
||||
- ✅ No hardcoded values
|
||||
- ✅ SQL optimized queries
|
||||
- ✅ Async-ready
|
||||
- ✅ Docker-ready
|
||||
- ✅ Scalable repositories
|
||||
- ✅ Comprehensive models
|
||||
|
||||
---
|
||||
|
||||
**Готово к разработке фич!** 🚀
|
||||
Reference in New Issue
Block a user