> ## 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]
>
> У пользователя может быть только **один активный тикет** (открытый или отвеченный). Для создания нового необходимо закрыть текущий.

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

* **Мои тикеты** — список открытых/отвеченных тикетов с пагинацией (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 без перезапуска.

> [!WARNING]
>
> **Изменение дефолтов в `v3.66.0`.** Раньше значения по умолчанию в коде расходились с `.env.example`: без явных настроек бот поднимался с включённым SLA, порогом 5 минут и повтором каждые 15 — админам летел поток напоминаний по каждому тикету. Теперь дефолты совпадают с `.env.example` и SLA выключен, пока его не включат явно.

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

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

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

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

Все действия модераторов логируются в журнал аудита с пометкой `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**: полный доступ через токен (статус, приоритет, блокировки, ответы, медиа)

### WebSocket для мобильной поддержки

Начиная с `v3.63.0` доступен WebSocket-канал живой переписки (`v1`), в `v3.66.0` к нему добавлен мост событий тикетов.

* Субпротокол: `bedolaga.support.mobile.v1`
* Авторизация: JWT кабинета или `initData` Telegram Mini App
* События: `ticket.created`, `ticket.status_changed`, `message.created`
* Медиа: те же ограничения на типы и размер файлов, что и в HTTP-загрузке

> [!NOTE]
>
> Канал проходит те же проверки, что и обычные тикеты: блокировка в поддержке, режим тикет-системы, лимит открытых тикетов, режим техработ. Повторы идемпотентны — переотправка одного сообщения не создаёт дубль, а ответы синхронизированы с Telegram-веткой того же тикета.

### Отказы видны пользователю

С `v1.66.0` кабинета отказ бэкенда показывается в форме, а не проглатывается молча: 409 «уже есть открытый тикет», 403 при блокировке в поддержке, 400 на закрытом тикете. Раньше это выглядело как «кнопка Отправить не работает».


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.