> ## 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.

# Админские уведомления в чаты

> Все типы уведомлений, отчётов и файлов, отправляемых в админские Telegram-чаты

## Обзор

Бот отправляет **35+ типов уведомлений** в админские Telegram-чаты. Уведомления маршрутизируются по топикам внутри супергруппы — каждый тип событий можно направить в отдельный топик.

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

### Основной чат уведомлений

```env theme={null}
# Включить уведомления (по умолчанию выключено)
ADMIN_NOTIFICATIONS_ENABLED=true

# ID супергруппы для уведомлений
ADMIN_NOTIFICATIONS_CHAT_ID=-1001234567890

# ID топика для общих уведомлений (опционально)
ADMIN_NOTIFICATIONS_TOPIC_ID=123
```

### Специализированные топики

Каждый тип событий можно направить в свой топик. Если специальный топик не указан — уведомления уходят в `ADMIN_NOTIFICATIONS_TOPIC_ID`.

#### Топики по категориям

```env theme={null}
# Покупки подписок (первичные покупки, гостевые покупки)
ADMIN_NOTIFICATIONS_PURCHASES_TOPIC_ID=

# Продления подписок
ADMIN_NOTIFICATIONS_RENEWALS_TOPIC_ID=

# Активации триалов
ADMIN_NOTIFICATIONS_TRIALS_TOPIC_ID=

# Пополнения баланса
ADMIN_NOTIFICATIONS_BALANCE_TOPIC_ID=

# Докупка трафика, устройств, серверов
ADMIN_NOTIFICATIONS_ADDONS_TOPIC_ID=

# Инфраструктура: ноды, техработы, статус панели, RemnaWave webhook-события
ADMIN_NOTIFICATIONS_INFRASTRUCTURE_TOPIC_ID=

# Ошибки бота, крэш-репорты
ADMIN_NOTIFICATIONS_ERRORS_TOPIC_ID=

# Промокоды, кампании, смена промогруппы, конкурсы
ADMIN_NOTIFICATIONS_PROMO_TOPIC_ID=

# Партнёрские заявки, выводы средств, массовые действия
ADMIN_NOTIFICATIONS_PARTNERS_TOPIC_ID=
```

#### Отдельные топики (настраиваются независимо)

| Переменная                                   | Назначение               | Фоллбэк                        |
| -------------------------------------------- | ------------------------ | ------------------------------ |
| `ADMIN_NOTIFICATIONS_TOPIC_ID`               | Общие уведомления        | General (без топика)           |
| `ADMIN_NOTIFICATIONS_TICKET_TOPIC_ID`        | Тикеты поддержки         | `ADMIN_NOTIFICATIONS_TOPIC_ID` |
| `ADMIN_NOTIFICATIONS_NALOG_TOPIC_ID`         | Очередь чеков NaloGO     | `ADMIN_NOTIFICATIONS_TOPIC_ID` |
| `SUSPICIOUS_NOTIFICATIONS_TOPIC_ID`          | Аномалии трафика         | `ADMIN_NOTIFICATIONS_TOPIC_ID` |
| `REFERRAL_WITHDRAWAL_NOTIFICATIONS_TOPIC_ID` | Запросы на вывод средств | `ADMIN_NOTIFICATIONS_TOPIC_ID` |

<Tip>
  Все топики по категориям опциональны. Если переменная не задана — уведомления автоматически уходят в `ADMIN_NOTIFICATIONS_TOPIC_ID`. Можно настроить только нужные топики, остальные останутся в общем.
</Tip>

### Чат отчётов

```env theme={null}
ADMIN_REPORTS_ENABLED=true
ADMIN_REPORTS_CHAT_ID=-1001234567890
ADMIN_REPORTS_TOPIC_ID=456
ADMIN_REPORTS_SEND_TIME=09:00
```

Если `ADMIN_REPORTS_CHAT_ID` не указан — отчёты отправляются в `ADMIN_NOTIFICATIONS_CHAT_ID`.

### Чат бэкапов

```env theme={null}
BACKUP_SEND_CHAT_ID=-1001234567890
BACKUP_SEND_TOPIC_ID=789
```

### Чат логов

```env theme={null}
LOG_ROTATION_ENABLED=true
LOG_ROTATION_SEND_TO_TELEGRAM=true
LOG_ROTATION_CHAT_ID=-1001234567890
LOG_ROTATION_TOPIC_ID=101
```

Если `LOG_ROTATION_CHAT_ID` не указан — логи отправляются в `BACKUP_SEND_CHAT_ID`.

***

## Финансовые уведомления

### Пополнение баланса

Отправляется при каждом успешном платеже через любую платёжную систему.

**Содержимое:**

* Пользователь (имя, ID, username)
* Статус: первое или повторное пополнение
* Промогруппа (если есть)
* Сумма и способ оплаты
* Баланс до → после
* Статус подписки (триал/активна/неактивна)
* Реферер (если есть)
* Технические детали: ID транзакции, внешний ID, UUID чека

### Покупка подписки

Отправляется при покупке, продлении, конверсии из триала или смене тарифа.

**Заголовок меняется в зависимости от типа:**

* Первая покупка → «Покупка подписки»
* Повторная → «Продление подписки»
* Из триала → «Конверсия из триала»
* Смена тарифа → «Смена тарифа»

**Содержимое:**

* Пользователь, тариф, способ оплаты, сумма
* Период, дата окончания, трафик, устройства, серверы
* Баланс после покупки, реферер, ID транзакции

### Продление подписки

Отправляется при явном продлении существующей подписки.

**Содержимое:**

* Пользователь, промогруппа с деталями скидок
* Сумма, способ оплаты, ID транзакции
* Добавленные дни, старая → новая дата окончания
* Текущие параметры: трафик, устройства, серверы

### Докупка трафика/устройств/серверов

Отправляется при покупке дополнений к подписке.

**Заголовок:** «Докупка трафика» / «Докупка устройств» / «Смена серверов»

**Содержимое:**

* Пользователь, тариф
* Изменение: старое → новое значение
* Стоимость, дата окончания подписки, баланс

***

## Подписки и триалы

### Активация триала

Отправляется при активации пробной подписки.

**Содержимое:**

* Пользователь, статус (новый/существующий)
* Промогруппа, тариф (если тарифный режим)
* Параметры триала: длительность, трафик, устройства, сервер
* Оплата за активацию (если платный триал)
* Дата окончания, реферер

***

## Промо и маркетинг

### Активация промокода

**Содержимое:**

* Пользователь, промогруппа
* Код, тип (деньги / дни подписки / триал), использований
* Бонус (сумма или дни), срок действия
* Баланс до → после, эффект

### Переход по рекламной кампании

Отправляется при клике по deep-ссылке кампании.

**Содержимое:**

* Кампания: название, ID, стартовый параметр
* Пользователь, статус (новый/существующий)
* Промогруппа, бонус кампании (баланс или подписка)

### Смена промогруппы

Отправляется при автоматической (по лояльности) или ручной смене промогруппы.

**Содержимое:**

* Пользователь
* Новая группа с деталями скидок
* Предыдущая группа (если была)
* Инициатор (админ или «Автоматически»), причина

***

## Поддержка

### Новый тикет

Отправляется в топик `ADMIN_NOTIFICATIONS_TICKET_TOPIC_ID`.

**Содержимое:** информация о пользователе, тема тикета, превью сообщения, кнопки для ответа.

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

Отправляется при ответе пользователя на существующий тикет.

### Напоминание о SLA

Автоматическая проверка каждые `SUPPORT_TICKET_SLA_CHECK_INTERVAL_SECONDS` (по умолчанию 60 сек). Если тикет без ответа дольше `SUPPORT_TICKET_SLA_MINUTES` (по умолчанию 5 мин) — отправляется напоминание.

```env theme={null}
SUPPORT_TICKET_SLA_ENABLED=true
SUPPORT_TICKET_SLA_MINUTES=5
SUPPORT_TICKET_SLA_CHECK_INTERVAL_SECONDS=60
SUPPORT_TICKET_SLA_REMINDER_COOLDOWN_MINUTES=15
```

Кулдаун между напоминаниями по одному тикету: `SUPPORT_TICKET_SLA_REMINDER_COOLDOWN_MINUTES`.

<Note>
  Уведомления о тикетах можно включить/выключить **без перезапуска** через настройки поддержки в админ-панели.
</Note>

***

## Партнёры и выводы

### Заявка на партнёрство

**Содержимое:**

* Пользователь
* Данные заявки: название компании, Telegram-канал, сайт, описание, ожидаемые рефералы

### Запрос на вывод средств

Отправляется в два места:

1. Основной топик уведомлений
2. Специальный топик `REFERRAL_WITHDRAWAL_NOTIFICATIONS_TOPIC_ID` (если настроен)

**Содержимое:**

* Пользователь, сумма вывода, текущий баланс, реквизиты

***

## Мониторинг и система

### Статус панели RemnaWave

Отправляется при изменении доступности панели.

| Статус      | Описание                                        |
| ----------- | ----------------------------------------------- |
| Online      | URL, время ответа, аптайм, пользователи онлайн  |
| Offline     | URL, ошибка, количество последовательных ошибок |
| Degraded    | Список проблем (до 3)                           |
| Maintenance | Причина, ожидаемое время                        |

### Режим обслуживания

Отправляется при включении/выключении техработ.

| Событие               | Описание                                        |
| --------------------- | ----------------------------------------------- |
| Включение             | Причина, время, автоматическое или ручное       |
| Выключение            | Время, длительность окна обслуживания           |
| API онлайн            | URL, время ответа, предыдущее количество ошибок |
| API оффлайн           | URL, номер попытки, текст ошибки                |
| Мониторинг запущен    | Интервал проверки, порог ошибок                 |
| Мониторинг остановлен | —                                               |

### Аномалии трафика

Отправляется в топик `SUSPICIOUS_NOTIFICATIONS_TOPIC_ID`.

```env theme={null}
TRAFFIC_MONITORING_ENABLED=true

# Быстрая проверка (каждые N минут)
TRAFFIC_FAST_CHECK_ENABLED=true
TRAFFIC_FAST_CHECK_INTERVAL_MINUTES=5

# Ежедневная проверка
TRAFFIC_DAILY_CHECK_ENABLED=true

# Кулдаун между уведомлениями по одному пользователю
TRAFFIC_NOTIFICATION_COOLDOWN_MINUTES=60
```

Максимум 10 уведомлений за одну проверку. Кулдаун на пользователя предотвращает спам.

### Массовая блокировка

Отправляется когда админ выполняет массовую блокировку пользователей.

**Содержимое:** имя админа, количество заблокированных, не найденных, ошибок, процент успеха.

***

## Обновления бота

### Доступно обновление

Бот проверяет GitHub раз в час. При обнаружении новой версии:

**Содержимое:**

* Тип: релиз / pre-release / dev build
* Версии: текущая → новая (со ссылкой на GitHub)
* Дата релиза, changelog
* Количество доступных обновлений

### Ошибка проверки обновлений

Если GitHub API недоступен — уведомление с ошибкой и информацией о повторной попытке через 1 час.

***

## Запуск и крэши

### Запуск бота

Отправляется один раз при успешном старте.

**Содержимое:**

* Версия бота
* Статистика: пользователи, активные подписки, общий баланс, открытые тикеты
* Статус панели RemnaWave
* Кнопки: GitHub, комьюнити, поддержка

### Крэш-репорт

Отправляется при фатальной ошибке запуска (webhook, БД, Redis, RemnaWave, авторизация).

**Содержимое:**

* Тип и текст ошибки
* Рекомендации по исправлению (зависят от типа ошибки)
* Прикреплённый файл `crash_report_{timestamp}.txt` с полным traceback

### Ошибки в хендлерах

Необработанные исключения автоматически отправляются в админ-чат.

**Содержимое:** файл `error_report_{timestamp}.txt` с traceback, контекстом хендлера и информацией о пользователе.

<Note>
  Отчёты об ошибках отправляются **даже если** `ADMIN_NOTIFICATIONS_ENABLED=false` — достаточно указать `ADMIN_NOTIFICATIONS_CHAT_ID`. Частота ограничена буфером (макс. 10 ошибок) и кулдауном.
</Note>

***

## Автоматические отчёты

### Ежедневный отчёт

Отправляется автоматически в `ADMIN_REPORTS_SEND_TIME` (московское время).

```env theme={null}
ADMIN_REPORTS_ENABLED=true
ADMIN_REPORTS_CHAT_ID=-1001234567890
ADMIN_REPORTS_TOPIC_ID=456
ADMIN_REPORTS_SEND_TIME=09:00
```

**Содержимое:**

* Новые регистрации
* Активации триалов
* Конверсии триал → платная подписка
* Покупки подписок
* Сумма пополнений и платежей за подписки
* Тикеты поддержки (открытые/закрытые)
* Метрики активности пользователей
* Топ рефереров

### Еженедельный и ежемесячный отчёты

Формируются по запросу через админ-панель. Те же метрики, агрегированные за 7 или 30 дней.

***

## Бэкапы

### Уведомление о бэкапе

Отправляется после каждого автобэкапа (успех или ошибка).

| Результат      | Содержимое                  |
| -------------- | --------------------------- |
| Успех          | Размер файла, длительность  |
| Ошибка         | Детали ошибки               |
| Восстановление | Успех/ошибка восстановления |

### Файл бэкапа

Сам файл бэкапа отправляется в отдельный чат `BACKUP_SEND_CHAT_ID`.

```env theme={null}
BACKUP_SEND_CHAT_ID=-1001234567890
BACKUP_SEND_TOPIC_ID=789

# Интервал автобэкапов
BACKUP_INTERVAL_HOURS=24
BACKUP_TIME=03:00
```

Файл может быть защищён паролем (ZIP). Подпись содержит метаданные бэкапа.

***

## Ротация логов

Ежедневно в `LOG_ROTATION_TIME` архивируются лог-файлы (`bot.log`, `info.log`, `warning.log`, `error.log`, `payments.log`) и отправляются в чат.

```env theme={null}
LOG_ROTATION_ENABLED=true
LOG_ROTATION_SEND_TO_TELEGRAM=true
LOG_ROTATION_TIME=04:00
LOG_ROTATION_CHAT_ID=-1001234567890
LOG_ROTATION_TOPIC_ID=101
```

Файл: `tar.gz` архив с подписью, содержащей список логов и их размеры.

***

## RemnaWave Webhook-события

При настроенном RemnaWave webhook бот получает и пересылает в админ-чат события панели:

### Ноды

| Событие                          | Описание                    |
| -------------------------------- | --------------------------- |
| `node.created`                   | Новая нода зарегистрирована |
| `node.modified`                  | Конфигурация ноды изменена  |
| `node.enabled` / `node.disabled` | Нода включена/выключена     |
| `node.deleted`                   | Нода удалена                |
| `node.connection_lost`           | Потеря связи с нодой        |
| `node.connection_restored`       | Связь восстановлена         |
| `node.traffic_notify`            | Порог трафика ноды          |

### Сервисы

| Событие                          | Описание                            |
| -------------------------------- | ----------------------------------- |
| `service.panel_started`          | Панель запущена/перезапущена        |
| `service.login_attempt_failed`   | Неудачная попытка входа в панель    |
| `service.login_attempt_success`  | Успешный вход в панель              |
| `service.subpage_config_changed` | Изменение конфига страницы подписки |

### Биллинг нод (CRM)

| Событие                      | Описание                         |
| ---------------------------- | -------------------------------- |
| Оплата через 7 дней          | Напоминание о предстоящей оплате |
| Оплата через 48 часов        | Срочное напоминание              |
| Оплата через 24 часа         | Критическое напоминание          |
| Оплата сегодня               | Оплата в день платежа            |
| Просрочка 24ч / 48ч / 7 дней | Уведомления о просрочке          |

***

## Очередь чеков NaloGO

Статус очереди фискальных чеков отправляется в топик `ADMIN_NOTIFICATIONS_NALOG_TOPIC_ID`.

Кулдаун: 1 час между уведомлениями. Содержимое: статус очереди, количество ошибочных чеков, детали ошибок.

***

## Конкурсы

### Ежедневная сводка по конкурсу

Отправляется ежедневно во время активного реферального конкурса. Содержимое: текущие позиции участников, топ рефереров, количество рефералов.

### Итоги конкурса

Отправляется при завершении конкурса. Содержимое: финальные результаты, победители, общее количество рефералов.

***

## Сводная таблица

| Уведомление                  | Чат           | Топик (категория) | Флаг              | Частота        |
| ---------------------------- | ------------- | ----------------- | ----------------- | -------------- |
| Пополнение баланса           | NOTIFICATIONS | BALANCE           | ENABLED           | Событие        |
| Покупка подписки             | NOTIFICATIONS | PURCHASES         | ENABLED           | Событие        |
| Продление подписки           | NOTIFICATIONS | RENEWALS          | ENABLED           | Событие        |
| Докупка трафика/устройств    | NOTIFICATIONS | ADDONS            | ENABLED           | Событие        |
| Активация триала             | NOTIFICATIONS | TRIALS            | ENABLED           | Событие        |
| Активация промокода          | NOTIFICATIONS | PROMO             | ENABLED           | Событие        |
| Переход по кампании          | NOTIFICATIONS | PROMO             | ENABLED           | Событие        |
| Смена промогруппы            | NOTIFICATIONS | PROMO             | ENABLED           | Событие        |
| Заявка на партнёрство        | NOTIFICATIONS | PARTNERS          | ENABLED           | Событие        |
| Запрос на вывод              | NOTIFICATIONS | PARTNERS          | ENABLED           | Событие        |
| Массовая блокировка          | NOTIFICATIONS | PARTNERS          | ENABLED           | Событие        |
| Новый тикет                  | NOTIFICATIONS | TICKETS           | ENABLED + runtime | Событие        |
| Ответ на тикет               | NOTIFICATIONS | TICKETS           | ENABLED + runtime | Событие        |
| Напоминание SLA              | NOTIFICATIONS | TICKETS           | SLA\_ENABLED      | Интервал       |
| Аномалии трафика             | NOTIFICATIONS | SUSPICIOUS\_TOPIC | Chat ID           | Интервал       |
| Статус панели                | NOTIFICATIONS | INFRASTRUCTURE    | ENABLED           | Событие        |
| Режим обслуживания           | NOTIFICATIONS | INFRASTRUCTURE    | ENABLED           | Событие        |
| Доступно обновление          | NOTIFICATIONS | INFRASTRUCTURE    | ENABLED           | Ежечасно       |
| Ошибка обновления            | NOTIFICATIONS | INFRASTRUCTURE    | ENABLED           | Ежечасно       |
| Запуск бота                  | NOTIFICATIONS | INFRASTRUCTURE    | ENABLED           | При старте     |
| Крэш-репорт                  | NOTIFICATIONS | ERRORS            | ENABLED           | При крэше      |
| Ошибки хендлеров             | NOTIFICATIONS | ERRORS            | Chat ID           | Throttled      |
| Очередь NaloGO               | NOTIFICATIONS | NALOG\_TOPIC      | ENABLED           | 1ч кулдаун     |
| RemnaWave webhook (12 типов) | NOTIFICATIONS | INFRASTRUCTURE    | ENABLED           | Событие        |
| Сводка конкурса              | NOTIFICATIONS | PROMO             | Конкурс активен   | Ежедневно      |
| Итоги конкурса               | NOTIFICATIONS | PROMO             | Конкурс активен   | При завершении |
| Ежедневный отчёт             | REPORTS       | REPORTS\_TOPIC    | REPORTS\_ENABLED  | Ежедневно      |
| Файл бэкапа                  | BACKUP        | BACKUP\_TOPIC     | BACKUP\_CHAT set  | По расписанию  |
| Статус бэкапа                | NOTIFICATIONS | INFRASTRUCTURE    | ENABLED           | По расписанию  |
| Архив логов                  | LOG\_ROTATION | LOG\_TOPIC        | LOG\_ENABLED      | Ежедневно      |

<Warning>
  Бот **не должен** быть администратором в чате с топиками — иначе он будет отвечать на сообщения. Достаточно добавить бота как обычного участника. Для топиков нужна супергруппа с включёнными топиками.
</Warning>