bottohelp/ARCHITECTURE.md

# 🏗 Архитектура телеграм-бота

## Обзор

Проект телеграм-бота был полностью реструктурирован для улучшения поддерживаемости, масштабируемости и надежности. Новая модульная архитектура обеспечивает четкое разделение ответственности между компонентами.

## 🏛 Структура архитектуры

### Основные принципы

1. **Модульность** - каждый компонент имеет четко определенную ответственность
2. **Разделение слоев** - четкое разделение между API, бизнес-логикой и данными
3. **Зависимости** - использование dependency injection для связывания компонентов
4. **Тестируемость** - каждый модуль может быть протестирован независимо
5. **Расширяемость** - новые функции добавляются без изменения существующего кода

### Слои архитектуры

```
┌─────────────────────────────────────────────────────────┐
│                    Презентационный слой                  │
│              (Telegram API, Handlers)                   │
├─────────────────────────────────────────────────────────┤
│                  Бизнес-логика (Services)                │
├─────────────────────────────────────────────────────────┤
│                Доступ к данным (Repositories)           │
├─────────────────────────────────────────────────────────┤
│                     База данных                         │
└─────────────────────────────────────────────────────────┘
```

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

```
telegram_bot/
├── core/                      # Ядро приложения
│   ├── __init__.py
│   ├── application.py         # Главный класс приложения
│   ├── config.py              # Управление конфигурацией
│   ├── exceptions.py          # Кастомные исключения
│   ├── command_router.py      # Маршрутизатор команд
│   ├── message_router.py      # Маршрутизатор сообщений
│   ├── menu_manager.py        # Менеджер меню
│   ├── permissions.py         # Система ролей и разрешений
│   ├── unified_router.py      # Объединенный маршрутизатор
│   ├── middleware.py          # Middleware компоненты
│   └── monitoring.py          # Мониторинг и метрики
│
├── database/                  # Слой базы данных
│   ├── __init__.py
│   ├── models.py              # Модели данных
│   ├── repository.py          # Репозитории для работы с БД
│   └── migrations/            # Миграции БД (планируется)
│
├── services/                  # Бизнес-логика
│   ├── __init__.py
│   ├── role_service.py        # Сервис управления ролями
│   ├── user_service.py        # Сервис управления пользователями
│   ├── game_service.py        # Игровая логика
│   ├── moderation_service.py  # Модерация
│   ├── scheduler_service.py   # Планировщик постов
│   ├── welcome_service.py     # Сервис приветствий
│   └── donation_service.py    # Донаты и достижения
│
├── handlers/                  # Обработчики команд
│   ├── __init__.py
│   ├── base_handler.py        # Базовый обработчик
│   ├── user_handlers.py       # Пользовательские команды
│   ├── game_handlers.py       # Игровые команды
│   ├── admin_handlers.py      # Админские команды
│   ├── media_handlers.py      # Обработка медиа
│   └── moderation_handlers.py # Модерация
│
├── utils/                     # Вспомогательные утилиты
│   ├── __init__.py
│   ├── validators.py          # Валидация данных
│   ├── formatters.py          # Форматирование сообщений
│   └── helpers.py             # Вспомогательные функции
│
├── games/                     # Игровые модули
│   ├── __init__.py
│   ├── game_2048.py           # Игра 2048
│   ├── game_tetris.py         # Тетрис
│   ├── game_snake.py          # Змейка
│   └── game_base.py           # Базовый класс игр
│
├── new_bot.py                 # Точка входа новой архитектуры
├── bot.py                     # Старый монолитный файл (для совместимости)
├── requirements.txt
└── README.md
```

## 🔧 Компоненты системы

### Core (Ядро)

#### Application (`core/application.py`)
Главный класс приложения, организующий работу всех компонентов:
- Инициализация всех модулей
- Настройка обработчиков
- Управление жизненным циклом
- Обработка ошибок верхнего уровня
- Интеграция новой системы маршрутизации с fallback на старую

#### Новая система маршрутизации

##### UnifiedMessageRouter (`core/unified_router.py`)
Объединенный маршрутизатор для всех типов обновлений:
- Единая точка входа для обработки сообщений
- Интеграция CommandRouter, MessageTypeRouter и ContextMenuManager
- Централизованное управление маршрутизацией
- Логирование и мониторинг

##### CommandRouter (`core/command_router.py`)
Центральный маршрутизатор команд:
- Регистрация и маршрутизация команд
- Проверка прав доступа через middleware
- Обработка callback запросов
- Метаданные команд (описания, категории)

##### MessageTypeRouter (`core/message_router.py`)
Маршрутизатор типов сообщений:
- Обработка текстовых сообщений по паттернам
- Роутинг медиафайлов (голос, видео, фото)
- Поддержка регулярных выражений для фильтрации

##### ContextMenuManager (`core/menu_manager.py`)
Менеджер контекстных меню:
- Управление доступностью меню на основе ролей
- Кеширование меню для производительности
- Динамическое формирование меню

#### Система разрешений

##### PermissionManager (`core/permissions.py`)
Менеджер разрешений:
- Иерархия ролей пользователей (USER, MODERATOR, ADMIN, SUPER_ADMIN)
- Проверка прав доступа к командам
- Определение роли по ID пользователя или правам в чате
- Матрица разрешений для каждой роли

##### UserRole (Enum)
Перечисление ролей:
- USER - обычный пользователь
- MODERATOR - модератор с правами предупреждений
- ADMIN - администратор с полными правами модерации
- SUPER_ADMIN - супер-администратор с полным доступом

##### Permission (Enum)
Перечисление конкретных разрешений:
- USE_BASIC_COMMANDS - базовые команды
- WARN_USERS - предупреждение пользователей
- BAN_USERS - блокировка пользователей
- MANAGE_SYSTEM - управление системой

#### Config (`core/config.py`)
Система управления конфигурацией:
- Загрузка из переменных окружения
- Поддержка файлов конфигурации
- Валидация обязательных параметров
- Типизация конфигурации

#### Exceptions (`core/exceptions.py`)
Кастомные исключения для единообразной обработки ошибок:
- `BotException` - базовое исключение
- `ValidationError` - ошибки валидации
- `DatabaseError` - ошибки базы данных
- `PermissionError` - ошибки доступа

### Database (База данных)

#### Models (`database/models.py`)
Модели данных с типизацией:
- `User` - модель пользователя
- `Score` - очки и статистика
- `Error` - ошибки и отчеты
- `ScheduledPost` - запланированные посты
- `Achievement` - достижения

#### Repositories (`database/repository.py`)
Паттерн Repository для доступа к данным:
- `UserRepository` - работа с пользователями
- `ScoreRepository` - управление очками
- `ErrorRepository` - ошибки и отчеты
- `ScheduledPostRepository` - планировщик

### Services (Бизнес-логика)

#### RoleService (`services/role_service.py`)
Управление ролями пользователей:
- Создание и инициализация ролей
- Назначение ролей пользователям
- Проверка принадлежности к ролям
- Управление правами доступа

#### UserService (`services/user_service.py`)
Управление пользователями и профилями:
- Создание и обновление профилей
- Расчет рейтингов и рангов
- Управление достижениями
- Статистика активности
- Интеграция с RoleService для проверки прав

#### WelcomeService (`services/welcome_service.py`)
Сервис персонализированных приветствий:
- Генерация приветственных сообщений
- Доступные команды по ролям
- Персонализация на основе роли пользователя

### Handlers (Обработчики)

#### BaseHandler (`handlers/base_handler.py`)
Абстрактный базовый класс для всех обработчиков:
- Общие методы валидации
- Обработка ошибок
- Проверка прав доступа
- Логирование действий

#### UserHandlers (`handlers/user_handlers.py`)
Обработчики пользовательских команд:
- `/start`, `/help`, `/rank`
- `/leaderboard`, `/info`
- Обработка текстовых сообщений

### Utils (Утилиты)

#### Validators (`utils/validators.py`)
Валидация входящих данных:
- Проверка ID пользователей и чатов
- Валидация текста и ссылок
- Проверка форматов времени и сумм

#### Formatters (`utils/formatters.py`)
Форматирование вывода:
- Форматирование сообщений пользователей
- Создание клавиатур и меню
- Экранирование HTML

#### Helpers (`utils/helpers.py`)
Вспомогательные функции:
- Безопасное выполнение функций
- Работа с текстом и числами
- Обработка ошибок

## 🚀 Запуск новой архитектуры

### Требования

```bash
pip install python-telegram-bot==20.7 requests==2.31.0
```

### Конфигурация

Создайте файл `config_local.py` или настройте переменные окружения:

```python
# config_local.py
BOT_TOKEN = "ваш_токен_бота"
ADMIN_IDS = [123456789, 987654321]
OPENWEATHER_API_KEY = "ключ_погоды"
NEWS_API_KEY = "ключ_новостей"
OPENAI_API_KEY = "ключ_openai"
```

Или через переменные окружения:
```bash
export BOT_TOKEN="ваш_токен"
export ADMIN_IDS="123456789,987654321"
```

### Запуск

```bash
python new_bot.py
```

## 🔄 Миграция со старой архитектуры

### Пошаговый план миграции

1. **Создание резервной копии**
   ```bash
   cp bot.py bot_old.py
   cp telegram_bot.db telegram_bot_old.db
   ```

2. **Параллельный запуск**
   - Запустите новую архитектуру: `python new_bot.py`
   - Старая архитектура остается в `bot.py` для совместимости

3. **Тестирование функциональности**
   - Проверьте основные команды: `/start`, `/help`, `/rank`
   - Протестируйте игры и модерацию
   - Убедитесь в корректности работы базы данных

4. **Постепенная миграция**
   - Переносите обработчики по одному модулю
   - Тестируйте каждый модуль отдельно
   - Обновляйте документацию

5. **Полная замена**
   - Замените `bot.py` на новую версию
   - Обновите скрипты запуска
   - Удалите старый код после подтверждения работоспособности

## 📊 Преимущества новой архитектуры

### Поддерживаемость
- **Размер файлов**: Основной файл уменьшен с 3500+ до < 500 строк
- **Читаемость**: Каждый модуль имеет четкую ответственность
- **Отладка**: Легче находить и исправлять ошибки

### Масштабируемость
- **Добавление функций**: Новые возможности без изменения существующего кода
- **Командная разработка**: Каждый разработчик работает с отдельным модулем
- **Тестирование**: Unit и integration тесты для каждого компонента

### Надежность
- **Обработка ошибок**: Единообразная обработка на всех уровнях
- **Валидация**: Проверка данных на входе и выходе
- **Мониторинг**: Логирование действий и ошибок

### Производительность
- **Оптимизация**: Локализация узких мест и оптимизация
- **Кеширование**: Возможность добавления кеширования (Redis)
- **База данных**: Оптимизированные запросы

## 🔧 Расширение функциональности

### Добавление новой команды

1. **Создайте обработчик** в соответствующем модуле:
```python
class NewHandlers(BaseHandler):
    def get_command_handlers(self) -> Dict[str, Callable]:
        return {
            'new_command': self.handle_new_command
        }
```

2. **Добавьте бизнес-логику** в сервис:
```python
class NewService:
    async def process_new_feature(self, user_id: int) -> str:
        # Логика обработки
        pass
```

3. **Зарегистрируйте в приложении**:
```python
# В Application._initialize_handlers()
handlers['new'] = NewHandlers(self.config, NewService(...))
```

### Добавление новой игры

1. **Создайте игровой модуль** в `games/`:
```python
class NewGame(GameBase):
    async def start_game(self, user_id: int) -> str:
        # Логика игры
        pass
```

2. **Добавьте обработчик** в `GameHandlers`:
```python
async def handle_new_game(self, update: Update, context: ContextTypes):
    # Обработка команды игры
    pass
```

## 🧪 Тестирование

### Структура тестов

```
tests/
├── __init__.py
├── test_services/
│   ├── test_user_service.py
│   ├── test_game_service.py
│   └── test_moderation_service.py
├── test_handlers/
│   ├── test_user_handlers.py
│   ├── test_admin_handlers.py
│   └── test_game_handlers.py
├── test_utils/
│   ├── test_validators.py
│   └── test_formatters.py
└── test_integration/
    └── test_full_flow.py
```

### Запуск тестов

```bash
# Установка зависимостей для тестирования
pip install pytest pytest-asyncio pytest-mock

# Запуск всех тестов
pytest

# Запуск тестов конкретного модуля
pytest tests/test_services/test_user_service.py

# Запуск с покрытием
pytest --cov=telegram_bot
```

## 📈 Мониторинг и аналитика

### Метрики для отслеживания

- **Производительность**: Время ответа на команды
- **Надежность**: Количество ошибок и их типы
- **Использование**: Статистика команд и активность пользователей
- **Ресурсы**: Загрузка CPU, памяти, базы данных

### Инструменты мониторинга

- **Логирование**: Структурированные логи с уровнями важности
- **Метрики**: Сбор метрик с помощью библиотеки (например, `prometheus_client`)
- **Отчеты**: Регулярные отчеты об ошибках и использовании

## 🔒 Безопасность

### Меры защиты

- **Валидация входных данных**: Проверка всех пользовательских вводов
- **Rate limiting**: Ограничение частоты запросов
- **Санитизация**: Очистка данных перед сохранением
- **Доступ к API**: Безопасное хранение ключей API

### Лучшие практики

- **Принцип наименьших прав**: Минимальные разрешения для выполнения задач
- **Обработка ошибок**: Не раскрытие внутренней информации в сообщениях об ошибках
- **Логирование**: Безопасное логирование без чувствительных данных

## 📚 Документация

### Обновление документации

- **README.md**: Общая информация о проекте и запуске
- **ARCHITECTURE.md**: Подробное описание архитектуры (этот файл)
- **API.md**: Документация API для разработчиков
- **DEPLOYMENT.md**: Инструкции по развертыванию

### Генерация документации

```bash
# Автоматическая генерация документации (если используется Sphinx)
sphinx-build docs/ docs/_build/
```

## 🔄 Новая система маршрутизации

### Архитектура маршрутизации

```
Telegram Update
        ↓
UnifiedMessageRouter.handle_update()
        ↓
├── Команды (/start, /help) → CommandRouter
├── Текстовые сообщения → MessageTypeRouter
├── Callback запросы → CommandRouter (callback handlers)
├── Инлайн запросы → MessageTypeRouter
└── Медиа файлы → MessageTypeRouter
```

### Принципы работы

1. **Единая точка входа**: Все обновления проходят через `UnifiedMessageRouter`
2. **Разделение ответственности**: Каждый тип обновлений обрабатывается специализированным роутером
3. **Проверка прав**: Middleware проверяет разрешения перед выполнением команд
4. **Fallback система**: При сбое новой системы активируется старая система обработчиков
5. **Логирование**: Все операции маршрутизации логируются для отладки

### Преимущества новой системы

- **Централизованное управление**: Все маршруты в одном месте
- **Гибкость**: Легко добавлять новые типы обработчиков
- **Безопасность**: Встроенная проверка прав доступа
- **Отказоустойчивость**: Fallback на старую систему
- **Производительность**: Кеширование и оптимизация маршрутов

## 📨 Архитектура обработки сообщений

### Общая структура

Проект использует модульную архитектуру с четким разделением ответственности. Обработка сообщений происходит через многоуровневую систему маршрутизации с интегрированной системой разрешений.

### Ключевые компоненты

#### 1. **UnifiedMessageRouter** (`core/unified_router.py`)
Единая точка входа для всех обновлений от Telegram API:
- Определяет тип обновления (message, callback_query, inline_query, etc.)
- Распределяет обработку между специализированными роутерами
- Интегрирует CommandRouter, MessageTypeRouter и ContextMenuManager
- Логирует все операции маршрутизации

#### 2. **CommandRouter** (`core/command_router.py`)
Центральный маршрутизатор команд:
- Регистрирует и маршрутизирует команды (начинающиеся с `/`)
- Проверяет права доступа через middleware
- Обрабатывает callback-запросы
- Содержит метаданные команд (описания, категории)

#### 3. **MessageTypeRouter** (`core/message_router.py`)
Маршрутизатор типов сообщений:
- Обработка текстовых сообщений по паттернам (регулярные выражения)
- Роутинг медиафайлов (фото, видео, аудио, документы, голосовые)
- Поддержка регулярных выражений для фильтрации
- Регистрация обработчиков с учетом ролей пользователей

#### 4. **ContextMenuManager** (`core/menu_manager.py`)
Менеджер контекстных меню:
- Управляет доступностью меню на основе ролей
- Кеширует меню для производительности
- Динамически формирует меню
- Проверяет права доступа к элементам меню

#### 5. **PermissionManager** (`core/permissions.py`)
Система ролей и разрешений:
- Иерархия ролей: USER, MODERATOR, ADMIN, SUPER_ADMIN
- Проверка прав доступа к командам и функциям
- Определение роли по ID пользователя или правам в чате
- Матрица разрешений для каждой роли

#### 6. **Handlers** (`handlers/`)
Обработчики команд и сообщений:
- **BaseHandler** - абстрактный базовый класс с общими методами
- **GameHandlers** - игровые команды и механики
- **AdminHandlers** - административные функции
- **UserHandlers** - пользовательские команды
- **ModerationHandlers** - модерационные функции

#### 7. **Services** (`services/`)
Бизнес-логика:
- **GameService** - управление игровыми сессиями и логикой игр
- **UserService** - управление пользователями и профилями
- **ModerationService** - функции модерации
- **WelcomeService** - персонализированные приветствия

#### 8. **Database** (`database/`)
Слой данных:
- Модели данных (User, Score, Warning, etc.)
- Репозитории для работы с БД
- Миграции базы данных

### Потоки данных

#### Основной поток обработки сообщений:
```
Telegram Update
    ↓
UnifiedMessageRouter.handle_update()
    ↓
├── Команды (/start, /help) → CommandRouter
├── Текстовые сообщения → MessageTypeRouter (по паттернам)
├── Callback запросы → CommandRouter (callback handlers)
├── Инлайн запросы → MessageTypeRouter
├── Медиа файлы → MessageTypeRouter
└── Меню → ContextMenuManager
    ↓
Handlers (с проверкой прав)
    ↓
Services (бизнес-логика)
    ↓
Database (сохранение данных)
```

#### Обработка игровой команды:
```
Команда /play_game
    ↓
GameHandlers.handle_play_game()
    ↓
GameService.create_game_session()
    ↓
Возврат клавиатуры выбора игры
    ↓
Callback от пользователя
    ↓
MessageTypeRouter.route_callback()
    ↓
GameHandlers.handle_2048() или другая игра
    ↓
GameService.play_game_logic()
    ↓
Database (обновление статистики)
```

#### Обработка административных команд:
```
Команда /admin_stats
    ↓
AdminHandlers.handle_admin_stats()
    ↓ (проверка прав ADMIN)
ModerationService.get_moderation_stats()
    ↓
Database (запрос статистики)
    ↓
Возврат результатов пользователю
```

### Система маршрутизации

#### Регистрация обработчиков:
- **Command handlers**: регистрируются в CommandRouter с указанием требуемой роли
- **Message handlers**: регистрируются в MessageTypeRouter с паттернами и ролями
- **Callback handlers**: регистрируются с паттернами callback_data
- **Media handlers**: регистрируются по типу медиа (photo, video, etc.)

#### Проверка прав доступа:
- Каждый обработчик имеет требуемую роль
- PermissionManager проверяет соответствие роли пользователя
- Иерархия ролей: SUPER_ADMIN > ADMIN > MODERATOR > USER

### Точки интеграции для новой системы триггеров

#### 1. **UnifiedMessageRouter** - основная точка интеграции
- Можно добавить новый тип обработки: триггеры
- Расширить `handle_update()` для обработки триггерных событий

#### 2. **MessageTypeRouter** - для текстовых паттернов
- Добавить регистрацию триггерных паттернов
- Интегрировать с базой данных триггеров

#### 3. **Services layer** - бизнес-логика триггеров
- Создать **TriggerService** для управления триггерами
- Хранение условий и действий триггеров
- Выполнение действий при срабатывании

#### 4. **Database layer** - хранение триггеров
- Добавить модели: Trigger, TriggerCondition, TriggerAction
- Репозитории для работы с триггерами
- Миграции для новых таблиц

#### 5. **Handlers** - обработчики триггеров
- **TriggerHandlers** для управления триггерами через команды
- Интеграция с существующими обработчиками

#### Возможные триггерные события:
- Текстовые паттерны в сообщениях
- Команды пользователей
- Изменения статуса пользователей
- Временные события (cron-like)
- Игровые события (победы, достижения)

#### Архитектура интеграции триггеров:
```
Сообщение пользователя
    ↓
UnifiedMessageRouter (расширенный)
    ↓
├── Обычная обработка
└── Проверка триггеров → TriggerService.check_triggers()
    ↓
TriggerService.execute_actions()
    ↓
Отправка ответов/выполнение действий
```

### Интеграция с Application

```python
# В Application.__init__()
self._initialize_unified_router()  # Создание компонентов
self._setup_unified_router()       # Регистрация обработчиков

# В обработчиках команд
async def _handle_command_fallback(self, update, context, command, handler):
    try:
        if self.unified_router:
            await self.unified_router.handle_update(update, context)
        else:
            await handler(update, context)  # Fallback
    except AttributeError:
        await handler(update, context)  # Безопасный fallback
```

## 🔮 Планы развития

### Короткосрочные цели (1-3 месяца)

- [x] Исправить синтаксическую ошибку в user_handlers.py
- [x] Реализовать fallback для unified_router
- [x] Добавить проверку инициализации unified_router
- [ ] Полная миграция на новую архитектуру
- [ ] Покрытие тестами > 80%
- [ ] Документация всех модулей
- [ ] Настройка мониторинга

### Среднесрочные цели (3-6 месяцев)

- [ ] Веб-интерфейс для управления ботом
- [ ] Многоязычность (i18n)
- [ ] Миграция на PostgreSQL
- [ ] Добавление Redis для кеширования

### Долгосрочные цели (6+ месяцев)

- [ ] Микросервисная архитектура
- [ ] Автоматическое масштабирование
- [ ] Расширенная аналитика и ML
- [ ] Интеграция с другими платформами

## 🤝 Вклад в развитие

### Рабочий процесс

1. **Создание задачи** в TODO.md или issue tracker
2. **Разработка** в отдельной ветке
3. **Тестирование** с покрытием > 80%
4. **Code review** другими разработчиками
5. **Слияние** после одобрения

### Стандарты кода

- **Типизация**: Использование type hints для всех функций
- **Документация**: Docstrings для всех публичных методов
- **Тестирование**: Unit тесты для всех новых функций
- **Стиль**: Соблюдение PEP 8 и проекта стандартов

---

*Последнее обновление: Октябрь 2025*
*Версия архитектуры: 2.0.0*