telegram-helper-bot/.cursor/rules/architecture.md

description, alwaysApply

description	alwaysApply
Архитектурные паттерны и структура проекта Telegram бота на aiogram	true

Архитектура проекта

Этот проект - Telegram бот на aiogram 3.10.0 с четкой архитектурой и разделением ответственности.

Структура проекта

helper_bot/
├── handlers/          # Обработчики событий (admin, callback, group, private, voice)
│   ├── services.py    # Бизнес-логика для каждого модуля
│   ├── exceptions.py  # Кастомные исключения модуля
│   └── dependencies.py # Dependency injection для модуля
├── middlewares/       # Middleware для cross-cutting concerns
├── utils/            # Утилиты и вспомогательные функции
├── keyboards/        # Клавиатуры для бота
└── filters/          # Кастомные фильтры

database/
├── repositories/     # Репозитории для работы с БД (Repository pattern)
├── models.py         # Модели данных
├── base.py           # Базовый класс DatabaseConnection
└── async_db.py       # AsyncBotDB - основной интерфейс к БД

Архитектурные паттерны

1. Repository Pattern

• Все операции с БД выполняются через репозитории в database/repositories/
• Каждая сущность имеет свой репозиторий (UserRepository, PostRepository, etc.)
• Репозитории наследуются от DatabaseConnection из database/base.py
• Используется RepositoryFactory для создания репозиториев

2. Service Layer Pattern

• Бизнес-логика вынесена в сервисы (handlers/*/services.py)
• Handlers только обрабатывают события и вызывают сервисы
• Сервисы работают с репозиториями через AsyncBotDB

3. Dependency Injection

• Используется BaseDependencyFactory для управления зависимостями
• Глобальный экземпляр доступен через get_global_instance()
• Зависимости внедряются через DependenciesMiddleware
• Для каждого модуля handlers может быть свой dependencies.py с фабриками

4. Middleware Pattern

• Middleware регистрируются в main.py на уровне dispatcher
• Порядок регистрации важен: DependenciesMiddleware → MetricsMiddleware → BlacklistMiddleware → RateLimitMiddleware
• Middleware обрабатывают cross-cutting concerns (логирование, метрики, rate limiting)

Принципы

1. Разделение ответственности: Handlers → Services → Repositories
2. Асинхронность: Все операции с БД и API асинхронные
3. Типизация: Используются type hints везде, где возможно
4. Логирование: Всегда через logs.custom_logger.logger
5. Метрики: Декораторы @track_time, @track_errors, @db_query_time для мониторинга

Версия Python

Проект использует Python 3.11.9 во всех окружениях:

• Локальная разработка: Python 3.11.9 (указана в .python-version)
• Docker (production): Python 3.11.9-alpine (указана в Dockerfile)
• Минимальная версия: Python 3.11 (указана в pyproject.toml)

Важно:

• При написании кода можно использовать фичи Python 3.11
• Доступны улучшенные type hints, match/case (Python 3.10+)
• Используйте type hints везде, где возможно
• @dataclass доступен (Python 3.7+)

Структура проекта:

• Docker файлы находятся в двух местах:
  • /prod/Dockerfile - для инфраструктуры (Python 3.11.9-alpine)
  • /prod/bots/telegram-helper-bot/Dockerfile - для бота (Python 3.11.9-alpine)
• При обновлении версии Python нужно обновить оба Dockerfile

Для локальной разработки: Рекомендуется использовать pyenv для установки Python 3.11.9:

pyenv install 3.11.9
pyenv local 3.11.9

Подробнее см. docs/PYTHON_VERSION_MANAGEMENT.md