83 lines
8.3 KiB
Markdown
83 lines
8.3 KiB
Markdown
# Поддержка
|
||
|
||
В проекте есть два канала поддержки:
|
||
|
||
- внешняя ссылка `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](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`.
|