mass refactor

docs/NATIVE_CHAT_SYSTEM.md

@@ -0,0 +1,123 @@
+# Система Нативных Чатов - Документация
+
+## Обзор
+Новая система нативных чатов обеспечивает более естественное взаимодействие пользователей в Telegram, заменяя сложные кнопочные интерфейсы на прямые сообщения.
+
+## Ключевые особенности
+
+### 1. Нативный интерфейс чатов
+- **Простой список чатов** без лишних кнопок
+- **Прямые сообщения** - пользователи могут просто печатать и отправлять
+- **Контекстное понимание** - бот автоматически определяет в каком чате находится пользователь
+
+### 2. Автоматические уведомления
+- **Мгновенные push-уведомления** о новых сообщениях
+- **Умные уведомления** - не спамят, отправляются только при необходимости
+- **Персонализированные сообщения** с именем отправителя
+
+### 3. Контекстная система
+- **30-минутное окно контекста** - бот помнит в каком чате пользователь
+- **Автоматическое переключение** между чатами
+- **Graceful timeout** - контекст сбрасывается через 30 минут неактивности
+
+## Архитектура
+
+### EnhancedChatHandlers
+Основной класс для обработки нативных чатов:
+
+```typescript
+- showChatsNative() - показывает список чатов
+- openNativeChat() - открывает конкретный чат
+- handleIncomingChatMessage() - обрабатывает входящие сообщения
+- sendMessageNotification() - отправляет уведомления
+- showChatHistory() - показывает историю сообщений
+```
+
+### Интеграция с MessageHandlers
+- Автоматическое перехватывание сообщений
+- Проверка контекста чата перед обработкой
+- Fallback на стандартную обработку если не в чате
+
+### Callback Integration
+Новые callback handlers:
+- `native_chats` - открывает нативный интерфейс чатов
+- `open_native_chat_<matchId>` - открывает конкретный чат
+- `chat_history_<matchId>` - показывает историю
+
+## Пользовательский опыт
+
+### Старый способ (сложный)
+1. Нажать "Открыть чаты"
+2. Выбрать чат из списка
+3. Нажать "Отправить сообщение"
+4. Написать сообщение
+5. Подтвердить отправку
+
+### Новый способ (нативный)
+1. Нажать "Нативные чаты"
+2. Выбрать чат
+3. Просто написать сообщение и отправить
+4. Получить автоматическое уведомление об ответе
+
+## Технические детали
+
+### Хранение контекста
+```typescript
+private activeChatContexts: Map<number, {
+    matchId: string;
+    partnerId: number;
+    lastActivity: Date;
+}> = new Map();
+```
+
+### Уведомления
+- Проверка активности получателя
+- Избежание дублирования уведомлений
+- Персонализированные сообщения
+
+### База данных
+- Используется существующая структура messages
+- Автоматическое сохранение всех сообщений
+- Совместимость со старой системой
+
+## Преимущества
+
+1. **Интуитивность** - привычный интерфейс Telegram
+2. **Скорость** - меньше кликов для отправки сообщения
+3. **Уведомления** - пользователи не пропустят сообщения
+4. **Контекст** - бот понимает в каком чате находится пользователь
+5. **Совместимость** - работает параллельно со старой системой
+
+## Настройки
+
+### Timeout контекста
+По умолчанию: 30 минут
+Можно изменить в константе `CHAT_CONTEXT_TIMEOUT_MS`
+
+### Уведомления
+Автоматически отправляются при:
+- Получении нового сообщения
+- Если получатель не в активном чате
+- Если прошло достаточно времени с последнего уведомления
+
+## Безопасность
+
+- Проверка существования матча перед отправкой
+- Валидация прав доступа к чату
+- Защита от спама уведомлениями
+- Автоматическая очистка неактивных контекстов
+
+## Миграция
+
+Система полностью обратно совместима:
+- Старые чаты продолжают работать
+- Новые пользователи автоматически используют нативный интерфейс
+- Постепенная миграция существующих пользователей
+
+## Мониторинг
+
+Логирование всех ключевых событий:
+- Отправка сообщений
+- Переключение контекста
+- Отправка уведомлений
+- Ошибки и исключения