> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bedolagam.ru/llms.txt
> Use this file to discover all available pages before exploring further.

# Система поддержки

> Тикеты, SLA, модераторы и каналы коммуникации

## Обзор

Система поддержки работает в трёх режимах, задаваемых переменной `SUPPORT_SYSTEM_MODE`:

| Режим     | Описание                                      |
| --------- | --------------------------------------------- |
| `tickets` | Только тикет-система                          |
| `contact` | Только ссылка на контакт (`SUPPORT_USERNAME`) |
| `both`    | Тикеты + ссылка на контакт (по умолчанию)     |

Режим переключается без перезапуска бота из админ-панели.

## Тикеты для пользователей

### Создание тикета

1. Пользователь нажимает **"Поддержка"** в главном меню
2. Выбирает **"Создать тикет"**
3. Вводит **заголовок** (5-255 символов)
4. Вводит **описание** (10-500 символов) или отправляет **фото** с подписью
5. Тикет создаётся со статусом `open` и приоритетом `normal`
6. Администратор получает уведомление

<Warning>
  У пользователя может быть только **один активный тикет** (открытый или отвеченный). Для создания нового необходимо закрыть текущий.
</Warning>

### Просмотр тикетов

* **Мои тикеты** — список открытых/отвеченных тикетов с пагинацией (10 на страницу)
* **Закрытые тикеты** — отдельная вкладка с историей
* Детальный просмотр с историей сообщений (разбивка по 3500 символов на страницу)
* Кнопка **"Вложения"** для просмотра фото (отправляются как медиагруппа)

### Ответ на тикет

* Текст 5-400 символов или фото с подписью
* При ответе пользователя статус меняется на `open`
* Антиспам: 1 сообщение в 2 секунды, подавление дублей после создания (6 сек)

### Закрытие тикета

Пользователь может закрыть свой тикет в любой момент. История сообщений сохраняется (только чтение).

## Статусы и приоритеты

### Статусы тикетов

| Статус     | Описание                                            |
| ---------- | --------------------------------------------------- |
| `open`     | Открыт, ожидает ответа администратора               |
| `answered` | Администратор ответил, ожидает реакции пользователя |
| `pending`  | В обработке                                         |
| `closed`   | Закрыт                                              |

### Приоритеты

| Приоритет | Описание               |
| --------- | ---------------------- |
| `low`     | Низкий                 |
| `normal`  | Обычный (по умолчанию) |
| `high`    | Высокий                |
| `urgent`  | Срочный                |

## Администрирование тикетов

### Просмотр

* Два раздела: **Открытые** (open + answered) и **Закрытые**
* Список с пагинацией (10 на страницу)
* Каждый тикет показывает: статус, приоритет, имя пользователя, username, Telegram ID
* Детальный просмотр с историей сообщений и ссылками на профиль пользователя

### Действия администратора

| Действие                    | Описание                                                                               |
| --------------------------- | -------------------------------------------------------------------------------------- |
| **Ответить**                | Текст до 400 символов или фото. Статус → `answered`. Пользователь получает уведомление |
| **Закрыть**                 | Закрытие тикета. Действие логируется                                                   |
| **Закрыть все**             | Массовое закрытие всех открытых/отвеченных тикетов                                     |
| **Блокировка (временная)**  | Блокировка ответов на N минут (1 — 525 600 = 1 год)                                    |
| **Блокировка (постоянная)** | Постоянная блокировка ответов пользователя                                             |
| **Разблокировка**           | Снятие любой блокировки                                                                |

Все действия записываются в **журнал аудита** (`support_audit_logs`).

## SLA-система

SLA-мониторинг проверяет тикеты без ответа администратора и отправляет уведомления при нарушении.

### Как работает

1. Фоновая задача проверяет тикеты через заданный интервал
2. Если тикет со статусом `open` не получил ответа дольше, чем `SLA_MINUTES` — отправляется уведомление
3. Повторные напоминания отправляются с учётом cooldown
4. При ответе пользователя таймер SLA сбрасывается

### Настройка

| Переменная                                     | По умолчанию | Описание                                |
| ---------------------------------------------- | ------------ | --------------------------------------- |
| `SUPPORT_TICKET_SLA_ENABLED`                   | `false`      | Включить SLA-мониторинг                 |
| `SUPPORT_TICKET_SLA_MINUTES`                   | `60`         | Минут до нарушения SLA                  |
| `SUPPORT_TICKET_SLA_CHECK_INTERVAL_SECONDS`    | `300`        | Интервал проверки (секунды)             |
| `SUPPORT_TICKET_SLA_REMINDER_COOLDOWN_MINUTES` | `30`         | Cooldown между повторными напоминаниями |

<Note>
  Все параметры SLA можно менять в реальном времени из админ-панели бота или через Cabinet API без перезапуска.
</Note>

## Модераторы

Модераторы — обычные пользователи с ограниченным доступом к тикетам. Управление модераторами доступно из раздела настроек поддержки в админ-панели.

### Возможности модераторов

* Просмотр всех тикетов (открытых и закрытых)
* Ответ на тикеты
* Закрытие тикетов (единичное и массовое)
* Блокировка/разблокировка пользователей
* Просмотр вложений

Все действия модераторов логируются в журнал аудита с пометкой `is_moderator=True`.

### Управление

* **Добавить модератора** — указать Telegram ID
* **Удалить модератора** — указать Telegram ID
* **Список модераторов** — показать всех

Модераторы получают отдельную точку входа в интерфейсе бота (кнопка "Тикеты" в панели модератора).

## Вложения

Поддерживаются **фотографии**:

* Пользователи могут прикрепить фото при создании тикета или в ответе
* Администраторы могут отправить фото в ответе
* Фото хранятся как Telegram `file_id`
* Просмотр через кнопку "Вложения" — отправляются медиагруппой (до 10 фото)

### Мультимедиа-галерея

В одном сообщении тикета можно отправить **до 10 вложений** (фото, документы). Вложения группируются в медиагруппу и отображаются как галерея:

* Пользователь отправляет несколько фото или файлов одним сообщением (медиагруппой Telegram)
* Все вложения из медиагруппы привязываются к одному сообщению тикета
* При просмотре вложения отображаются как единая галерея
* Максимум **10 вложений** на одно сообщение (ограничение Telegram API)

## Уведомления

Тикет-система использует 4 канала уведомлений:

| Канал                   | Получатель                 | Триггеры                                        |
| ----------------------- | -------------------------- | ----------------------------------------------- |
| Telegram (админы)       | Чат администраторов        | Новый тикет, ответ пользователя, нарушение SLA  |
| Telegram (пользователь) | Личный чат пользователя    | Ответ администратора                            |
| Cabinet (БД)            | Веб-интерфейс              | Все события (с отметками прочитано/непрочитано) |
| WebSocket               | Cabinet в реальном времени | Новый тикет, ответы                             |

## Защита от злоупотреблений

* **Один активный тикет** — нельзя создать новый при наличии открытого
* **Глобальная блокировка** — заблокированный в любом тикете пользователь не может создавать новые
* **Rate limiting** — 1 сообщение в 2 секунды (через Redis)
* **Защита от дублей** — проверка FSM-состояния + подавление на 6 секунд после создания
* **Автоудаление сообщений** — пользовательские сообщения удаляются через 2 секунды для чистоты чата

## Настройки поддержки

### Основные переменные

| Переменная             | По умолчанию | Описание                             |
| ---------------------- | ------------ | ------------------------------------ |
| `SUPPORT_USERNAME`     | `@support`   | Контакт поддержки (username или URL) |
| `SUPPORT_MENU_ENABLED` | `true`       | Показывать меню поддержки            |
| `SUPPORT_SYSTEM_MODE`  | `both`       | Режим: `tickets`, `contact`, `both`  |

### Настройки из админ-панели (без перезапуска)

| Настройка                            | Описание                                   |
| ------------------------------------ | ------------------------------------------ |
| `system_mode`                        | Режим поддержки                            |
| `menu_enabled`                       | Показывать в главном меню                  |
| `support_info_texts`                 | Текст описания поддержки (HTML, по языкам) |
| `admin_ticket_notifications_enabled` | Telegram-уведомления для админов           |
| `user_ticket_notifications_enabled`  | Telegram-уведомления для пользователей     |
| `ticket_sla_enabled`                 | SLA-мониторинг                             |
| `ticket_sla_minutes`                 | Порог SLA                                  |
| `moderators`                         | Список модераторов                         |

### Уведомления

| Переменная                            | По умолчанию | Описание                     |
| ------------------------------------- | ------------ | ---------------------------- |
| `ADMIN_NOTIFICATIONS_CHAT_ID`         | —            | Telegram чат для уведомлений |
| `ADMIN_NOTIFICATIONS_TICKET_TOPIC_ID` | —            | ID топика для тикетов        |

## Cabinet и Web API

Тикет-система полностью доступна через Cabinet (веб-интерфейс) и Web API:

* **Пользователи**: создание тикетов, ответы, просмотр уведомлений (текст до 4000 символов)
* **Администраторы**: просмотр всех тикетов, ответы, смена статуса/приоритета, статистика
* **Web API**: полный доступ через токен (статус, приоритет, блокировки, ответы, медиа)