docs: refactor docs structure
This commit is contained in:
3252a8
@@ -0,0 +1,82 @@
|
||||
# Поддержка
|
||||
|
||||
В проекте есть два канала поддержки:
|
||||
|
||||
- внешняя ссылка `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](../configuration/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`.
|
||||
Reference in New Issue
Block a user