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

Подготовка к релизу

Browse Source
This commit is contained in:
alex
2025-10-30 18:28:26 +03:00
parent 69c0162c6b
commit 4981db90a0
191 changed files with 45557 additions and 3651 deletions
Download Patch File Download Diff File Expand all files Collapse all files
ARCHITECTURE.md
+731
View File
@@ -0,0 +1,731 @@
# 🏗 Архитектура телеграм-бота
## Обзор
Проект телеграм-бота был полностью реструктурирован для улучшения поддерживаемости, масштабируемости и надежности. Новая модульная архитектура обеспечивает четкое разделение ответственности между компонентами.
## 🏛 Структура архитектуры
### Основные принципы
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*