🚀 Support Bot v1.0 - Полнофункциональный бот поддержки для Telegram

📋 Описание

Support Bot - это профессиональный Telegram бот для организации службы поддержки пользователей с системой тикетов, базой знаний FAQ и удобной админ-панелью. Бот работает с Forum группами Telegram и автоматически создает отдельные темы (топики) для каждого обращения.

✨ Основные возможности

🎫 Система тикетов

Автоматическое создание тикетов - каждое обращение пользователя создает отдельную тему в Forum группе
Уникальная нумерация - каждый тикет получает уникальный ID (#ID1, #ID2 и т.д.)
Статусы тикетов - открытые (🔴) и закрытые (🟢) тикеты с визуальной индикацией
Автоматическое закрытие - тикеты можно закрывать как операторами, так и пользователями
Восстановление состояния - бот автоматически восстанавливает активные тикеты после перезапуска
Защита от дублирования - система предотвращает создание нескольких активных тикетов от одного пользователя

💬 Двусторонняя переписка

Полная синхронизация сообщений - все сообщения между пользователем и оператором синхронизируются
Поддержка ответов - можно отвечать на конкретные сообщения, сохраняется контекст переписки
Маппинг сообщений - система отслеживает соответствие сообщений между пользователем и топиком
Поддержка всех типов медиа - фото, видео, документы, аудио, текстовые сообщения

📚 База знаний FAQ

Неограниченное количество вопросов - создавайте сколько угодно FAQ
Медиа в ответах - к каждому FAQ можно прикрепить фото, видео или документ
Сортировка FAQ - можно менять порядок отображения вопросов (вверх/вниз)
HTML форматирование - поддержка форматирования текста в вопросах и ответах
Быстрая отправка - операторы могут отправлять готовые ответы из FAQ одним кликом
Публичный доступ - пользователи могут просматривать FAQ до создания обращения

🛡️ Система безопасности

Антиспам защита - защита от флуда (лимит 4 секунды между сообщениями)
Умный антиспам - первое сообщение при создании тикета всегда проходит, даже при быстрой отправке
Система банов - операторы могут блокировать и разблокировать пользователей
Причины бана - можно указать причину блокировки
Кеширование банов - быстрая проверка заблокированных пользователей
Синхронизация БД - баны сохраняются в базе данных и восстанавливаются после перезапуска

👨‍💼 Админ-панель

Управление главным меню - настройка текста и фото приветственного сообщения
Управление FAQ - полный CRUD для базы знаний
Настройка панели - возможность добавить ссылку на внешнюю панель управления
Контакт для разбана - настройка контакта для жалоб забаненных пользователей
Просмотр меню пользователя - возможность увидеть, что видит обычный пользователь

🎨 Пользовательский интерфейс

Интуитивное меню - удобная навигация с кнопками
Главное меню - настраиваемое приветственное сообщение с фото
Кнопка закрытия тикета - пользователь может самостоятельно закрыть обращение
Отмена создания тикета - возможность отменить создание обращения
Автоматические уведомления - пользователь получает подтверждения о создании/закрытии тикета

📱 Поддержка медиа

Альбомы - поддержка отправки нескольких фото/видео одновременно (до 10 в группе)
Все типы файлов - фото, видео, документы, аудио
Подписи к медиа - поддержка текстовых подписей к файлам
Копирование медиа - медиа корректно копируется между пользователем и оператором

⚙️ Команды для операторов

/ban [причина] - Заблокировать пользователя с указанием причины
/unban [ID] - Разблокировать пользователя (можно указать ID или использовать в топике)
/close - Закрыть текущий тикет
/check - Отправить пользователю вопрос "Могу помочь?"
/faq - Открыть меню для отправки ответа из FAQ
/checkban [ID] - Проверить статус бана пользователя

🔧 Команды для администраторов

/admin - Открыть админ-панель (в личных сообщениях)
/get_chat_id - Получить ID текущего чата (для настройки)

👤 Команды для пользователей

/start - Открыть главное меню

🛠 Технические особенности

🗄️ База данных

SQLite - легковесная база данных, не требует отдельного сервера
Автоматическое создание - все таблицы создаются автоматически при первом запуске
Резервное копирование - автоматическое создание бэкапов перед обновлением
Миграции - автоматическое обновление структуры БД при обновлении бота

📊 Таблицы БД

tickets - информация о тикетах (ID, пользователь, топик, статус, даты)
faq - база знаний (вопросы, ответы, порядок сортировки)
faq_media - медиа файлы для FAQ
settings - настройки бота (главное меню, панель, контакты)
banned_users - список заблокированных пользователей
message_map - маппинг сообщений для синхронизации переписки

🐳 Docker

Готовая конфигурация - docker-compose.yml для быстрого запуска
Автоматическая установка - скрипт установки настраивает все автоматически
Изолированная среда - бот работает в контейнере, не влияет на систему
Автозапуск - контейнер автоматически перезапускается при сбоях

🔄 Обновления

Автоматическое обновление - одна команда для обновления всех файлов
Сохранение данных - база данных и настройки сохраняются при обновлении
Резервные копии - автоматическое создание бэкапов перед обновлением
Без простоев - можно обновлять без потери данных

🚀 Установка

Одна команда - полностью автоматическая установка
Фиксированная директория - все файлы в /opt/support-bot/
Автоматическая установка Docker - если Docker не установлен, скрипт установит его
Проверка зависимостей - автоматическая проверка всех требований

🎯 Уникальные возможности

🧠 Умная обработка сообщений

Race condition защита - предотвращение дублирования тикетов при быстрой отправке
Self-healing - автоматическое восстановление состояния при несоответствиях
Обработка ошибок - корректная обработка всех исключений с логированием
Retry механизм - автоматические повторы при временных ошибках API

📨 Обработка альбомов

Группировка медиа - автоматическая группировка нескольких файлов в альбом
Разбивка на пачки - поддержка больших альбомов (разбивка по 10 файлов)
Сохранение порядка - медиа отправляются в правильном порядке
Одна подпись - подпись добавляется только к первому файлу в альбоме

🔐 Безопасность

Проверка банов - каждый запрос проверяет статус бана в БД
Синхронизация кеша - автоматическая синхронизация кеша с БД
Защита от повторных действий - защита от двойных нажатий кнопок
Валидация доступа - проверка прав доступа для всех команд

🎨 Настройка интерфейса

Кастомное главное меню - настраиваемый текст и фото
HTML форматирование - поддержка HTML во всех текстах
Отключение превью ссылок - можно отключить превью для FAQ
Кнопки действий - удобные inline-кнопки для всех действий

📦 Что входит в релиз

bot.py - основной файл бота (1549 строк кода)
docker-compose.yml - конфигурация Docker
Dockerfile - образ контейнера
requirements.txt - зависимости Python
install.sh - скрипт автоматической установки
update.sh - скрипт автоматического обновления
README.md - полная документация

🔧 Требования

Linux VPS/VM (Ubuntu/Debian рекомендуется)
Docker и docker-compose
Python 3.11+ (устанавливается автоматически в контейнере)
Forum группа в Telegram (обязательно!)

📝 Быстрый старт

# Установка (одна команда)
curl -sSL https://raw.githubusercontent.com/mdeadice/support-bot/main/install.sh | sudo bash

# Настройка
sudo nano /opt/support-bot/.env

# Запуск
cd /opt/support-bot && sudo docker-compose up -d

🎉 Особенности реализации

Асинхронность - полностью асинхронный код на aiogram 3.x
Обработка ошибок - комплексная обработка всех типов ошибок
Логирование - подробное логирование всех операций
Производительность - оптимизированный код с кешированием
Масштабируемость - готов к работе с большим количеством пользователей
Надежность - защита от всех типов сбоев и ошибок

📈 Статистика кода

~1549 строк основного кода
7 таблиц в базе данных
37 обработчиков команд и callback'ов
Полная документация в README

🔄 История версий

v1.0 (Текущий релиз)

✅ Полнофункциональная система тикетов
✅ База знаний FAQ с медиа
✅ Админ-панель
✅ Система банов
✅ Поддержка альбомов
✅ Автоматическая установка и обновление
✅ Защита от антиспама для первого сообщения
✅ Двусторонняя переписка с маппингом сообщений
✅ Автоматическое восстановление состояния

📄 Лицензия

MIT License - свободное использование и модификация

Создано с ❤️ для удобной организации поддержки пользователей

🚀 Support Bot v1.0