Поддержка

В проекте есть два канала поддержки:

• внешняя ссылка SUPPORT_LINK, которая ведет пользователя в Telegram-чат, канал, форму или любой другой публичный URL;
• встроенные тикеты Web App / Mini App, если включен SUPPORT_TICKETS_ENABLED.

Внешняя ссылка остается простым резервным каналом. Тикеты дают полноценный диалог внутри личного кабинета: пользователь создает обращение, видит историю ответов, получает счетчик непрочитанных сообщений, а администратор отвечает из админ-панели.

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

Раздел Поддержка появляется в Web App, когда SUPPORT_TICKETS_ENABLED=True. Пользователь может:

• создать тикет с темой, категорией, приоритетом и первым сообщением;
• выбрать категорию billing, technical, account или other;
• выбрать приоритет normal или high;
• открыть список своих тикетов с фильтром по активным и всем обращениям;
• отвечать в открытом тикете и видеть ответы поддержки;
• перейти по SUPPORT_LINK, если нужна внешняя поддержка.

Заблокированные пользователи не могут создавать тикеты и отвечать в них. Для пользователей показываются только обычные сообщения: внутренние заметки администраторов скрыты.

Админский сценарий

В админ-панели тикеты доступны в разделе Коммуникации -> Поддержка. Доступ проверяется так же, как и для остальных /api/admin/*: нужна Web App-сессия пользователя, чей Telegram ID указан в ADMIN_IDS.

Администратор может:

• видеть сводку по открытым, ожидающим ответа, закрытым и непрочитанным тикетам;
• фильтровать обращения по статусу, приоритету, категории и назначенному администратору;
• искать по теме, username, имени и email пользователя;
• сортировать по обновлению, созданию или важности;
• отвечать пользователю, менять статус, категорию, приоритет и исполнителя;
• оставлять внутренние заметки, которые видны только администраторам;
• открыть карточку пользователя и видеть контекст подписки: тариф, статус, остаток времени, обычный и premium-трафик.

Статусы тикета: open, awaiting_user, awaiting_admin, resolved, closed. При создании тикет сразу получает статус awaiting_admin; ответ пользователя переводит незакрытый тикет в awaiting_admin, ответ администратора - в awaiting_user. Закрытые статусы считаются resolved и closed.

Уведомления

Новые тикеты и ответы пользователя могут отправляться в Telegram-уведомления администраторам и в лог-чат. Для отдельного топика поддержки используйте LOG_SUPPORT_THREAD_ID; если он пустой, сообщения идут в общий LOG_THREAD_ID/чат по настройкам логирования.

Повторные уведомления по одному непрочитанному тикету ограничиваются cooldown-настройками, чтобы не заспамить админов:

• SUPPORT_ADMIN_NOTIFICATION_COOLDOWN_SECONDS - пауза для Telegram/log уведомлений;
• SUPPORT_ADMIN_EMAIL_COOLDOWN_SECONDS - пауза для email-уведомлений.

Email-уведомления администраторам включаются через SUPPORT_ADMIN_EMAIL_NOTIFICATIONS_ENABLED=True. Письма отправляются только администраторам из ADMIN_IDS, у которых в базе есть email. Для отправки нужен рабочий SMTP-конфиг, как и для входа по email.

Ответ администратора и закрытие тикета дополнительно отправляются пользователю в Telegram, если у него есть Telegram-аккаунт, и на email, если он привязан.

Настройки

Переменная	Назначение
SUPPORT_LINK	Внешняя ссылка поддержки. Показывается в боте и Web App как быстрый способ связаться с командой.
SUPPORT_TICKETS_ENABLED	Включает раздел тикетов в Mini App и разрешает создание обращений.
SUPPORT_TICKET_MAX_BODY_LENGTH	Максимальная длина сообщения тикета.
SUPPORT_TICKET_MAX_SUBJECT_LENGTH	Максимальная длина темы тикета.
SUPPORT_TICKET_RATE_LIMIT_PER_HOUR	Сколько новых тикетов пользователь может создать за час; 0 отключает лимит.
LOG_SUPPORT	Включает Telegram/log уведомления по тикетам поддержки.
LOG_SUPPORT_THREAD_ID	Необязательный ID топика в лог-чате для сообщений поддержки.
SUPPORT_ADMIN_EMAIL_NOTIFICATIONS_ENABLED	Включает email-уведомления администраторам о новых тикетах и ответах пользователей.
SUPPORT_ADMIN_NOTIFICATION_COOLDOWN_SECONDS	Минимальная пауза между повторными Telegram/log уведомлениями по одному непрочитанному тикету.
SUPPORT_ADMIN_EMAIL_COOLDOWN_SECONDS	Минимальная пауза между повторными email-уведомлениями по одному непрочитанному тикету.

Все эти параметры описаны в env-vars.md. Основной рекомендуемый способ менять их - админка Система -> Настройки -> Поддержка; значения применяются как override поверх .env.

API и хранение

Пользовательские маршруты:

• GET /api/support/tickets - список тикетов пользователя;
• POST /api/support/tickets - создать тикет;
• GET /api/support/tickets/{id} - открыть тикет;
• POST /api/support/tickets/{id}/messages - отправить ответ;
• POST /api/support/tickets/{id}/read - отметить сообщения прочитанными;
• GET /api/support/unread - счетчик непрочитанных ответов поддержки.

Админские маршруты находятся под /api/admin/support/*: список, карточка тикета, ответ, изменение статуса/приоритета/категории/исполнителя, отметка прочитанного и статистика.

Данные хранятся в таблицах support_tickets и support_ticket_messages; миграция применяется автоматически сервисом migrate при docker compose up -d --build.