124 lines
5.8 KiB
Markdown
124 lines
5.8 KiB
Markdown
# Система Нативных Чатов - Документация
|
||
|
||
## Обзор
|
||
Новая система нативных чатов обеспечивает более естественное взаимодействие пользователей в 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`
|
||
|
||
### Уведомления
|
||
Автоматически отправляются при:
|
||
- Получении нового сообщения
|
||
- Если получатель не в активном чате
|
||
- Если прошло достаточно времени с последнего уведомления
|
||
|
||
## Безопасность
|
||
|
||
- Проверка существования матча перед отправкой
|
||
- Валидация прав доступа к чату
|
||
- Защита от спама уведомлениями
|
||
- Автоматическая очистка неактивных контекстов
|
||
|
||
## Миграция
|
||
|
||
Система полностью обратно совместима:
|
||
- Старые чаты продолжают работать
|
||
- Новые пользователи автоматически используют нативный интерфейс
|
||
- Постепенная миграция существующих пользователей
|
||
|
||
## Мониторинг
|
||
|
||
Логирование всех ключевых событий:
|
||
- Отправка сообщений
|
||
- Переключение контекста
|
||
- Отправка уведомлений
|
||
- Ошибки и исключения
|