FerraSoft/bottohelp
1
0
Fork 0
mirror of https://github.com/FerraSoft/bottohelp.git synced 2026-08-06 21:55:03 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
4aa9f8309e5356ed2019b01ceabc9a379c7a5573
bottohelp/ARCHITECTURE.md
T

33 KiB
Raw Blame History

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

Обзор

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

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

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

  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)

Вспомогательные функции:

  • Безопасное выполнение функций
  • Работа с текстом и числами
  • Обработка ошибок

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

Требования

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

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

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

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

Или через переменные окружения:

export BOT_TOKEN="ваш_токен"
export ADMIN_IDS="123456789,987654321"

Запуск

python new_bot.py

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

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

  1. Создание резервной копии

    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. Создайте обработчик в соответствующем модуле:
class NewHandlers(BaseHandler):
    def get_command_handlers(self) -> Dict[str, Callable]:
        return {
            'new_command': self.handle_new_command
        }
  1. Добавьте бизнес-логику в сервис:
class NewService:
    async def process_new_feature(self, user_id: int) -> str:
        # Логика обработки
        pass
  1. Зарегистрируйте в приложении:
# В Application._initialize_handlers()
handlers['new'] = NewHandlers(self.config, NewService(...))

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

  1. Создайте игровой модуль в games/:
class NewGame(GameBase):
    async def start_game(self, user_id: int) -> str:
        # Логика игры
        pass
  1. Добавьте обработчик в GameHandlers:
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

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

# Установка зависимостей для тестирования
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: Инструкции по развертыванию

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

# Автоматическая генерация документации (если используется 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

# В 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 месяца)

  • Исправить синтаксическую ошибку в user_handlers.py
  • Реализовать fallback для unified_router
  • Добавить проверку инициализации 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

Reference in New Issue View Git Blame Copy Permalink