Поддержка пользователей / тикеты

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

внешняя ссылка 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.