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

# Рекламные кампании

> Deeplink-кампании с бонусами, аналитикой и партнёрской интеграцией

## Обзор

Рекламные кампании используют механизм Telegram Deep Links для привязки новых пользователей к источникам трафика. Каждая кампания генерирует уникальную ссылку вида:

```
https://t.me/{bot_username}?start={start_parameter}
```

При переходе по ссылке новый пользователь автоматически привязывается к кампании и может получить бонус.

## Типы бонусов

| Тип              | Описание                                        |
| ---------------- | ----------------------------------------------- |
| **balance**      | Начисление на баланс (в копейках)               |
| **subscription** | Триальная подписка с настраиваемыми параметрами |
| **tariff**       | Полноценная подписка по конкретному тарифу      |
| **none**         | Только отслеживание (без бонуса)                |

### Balance (баланс)

Фиксированная сумма начисляется на баланс пользователя. Пользователь видит сообщение: "Вы получили {сумма} за регистрацию по кампании '{название}'!"

### Subscription (триальная подписка)

Создаёт триальную подписку с параметрами:

| Параметр                     | Описание                                                        |
| ---------------------------- | --------------------------------------------------------------- |
| `subscription_duration_days` | Длительность (1-730 дней)                                       |
| `subscription_traffic_gb`    | Трафик в ГБ (0 = безлимит)                                      |
| `subscription_device_limit`  | Лимит устройств                                                 |
| `subscription_squads`        | Список серверов (UUID). Если пусто — случайный триальный сервер |

<Warning>
  Подписка не создаётся, если у пользователя уже есть активная подписка.
</Warning>

### Tariff (тарифная подписка)

Создаёт полноценную (не триальную) подписку по выбранному тарифу:

* `tariff_id` — ссылка на активный тариф
* `tariff_duration_days` — длительность (1-730 дней)
* Трафик, устройства и серверы наследуются из тарифа

### None (только отслеживание)

Бонус не выдаётся, но регистрация привязывается к кампании для аналитики.

## Механизм Deep Link

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

1. **Генерация ссылки** — каждая кампания имеет уникальный `start_parameter` (3-32 символа, `[A-Za-z0-9_-]`)
2. **Пользователь переходит** по ссылке `/start {parameter}`
3. **Обработка в боте**:
   * Ищет кампанию по `start_parameter`
   * Если найдена — сохраняет `campaign_id` в FSM
   * Если у кампании есть партнёр — устанавливает его как реферера
   * Если кампания не найдена — трактует параметр как реферальный код
4. **Бонус применяется** после завершения регистрации

### Сохранение через проверку канала

Если включена обязательная подписка на канал (`CHANNEL_IS_REQUIRED_SUB=true`), параметр кампании сохраняется в Redis и восстанавливается после подписки.

### Веб-ссылка для MiniApp

Дополнительный формат: `{MINIAPP_CUSTOM_URL}/?campaign={start_parameter}`

## Ограничения

* **Только для новых пользователей** — существующие видят "Эта ссылка доступна только для новых пользователей"
* **Один бонус на пользователя** — уникальность по `(campaign_id, user_id)`
* **Подавление welcome-оффера** — при регистрации через кампанию стандартный триал/welcome-оффер пропускается
* **Самореферирование** — партнёр не может получить бонус по своей кампании

## Партнёрская интеграция

Кампании можно привязать к **партнёру** (`partner_user_id`):

* При создании/редактировании выбирается из одобренных партнёров (`partner_status='approved'`)
* Переход по партнёрской кампании автоматически делает партнёра реферером нового пользователя
* Все реферальные доходы от пользователей кампании отмечаются `campaign_id` в таблице `referral_earnings`
* На странице партнёра в Cabinet отображается статистика по каждой кампании: регистрации, рефералы, доход

## Аналитика

### Метрики по кампании

| Метрика                       | Описание                        |
| ----------------------------- | ------------------------------- |
| `registrations`               | Всего зарегистрировано          |
| `balance_issued`              | Всего начислено на баланс       |
| `subscription_issued`         | Количество выданных подписок    |
| `total_revenue_kopeks`        | Доход от пользователей кампании |
| `conversion_rate`             | Конверсия в оплату (%)          |
| `trial_conversion_rate`       | Конверсия триала в оплату (%)   |
| `avg_revenue_per_user_kopeks` | Средний доход на пользователя   |
| `avg_first_payment_kopeks`    | Средний первый платёж           |

### Графики и аналитика

В Cabinet админ-панели доступна расширенная аналитика по каждой кампании:

| Компонент                | Описание                                                          |
| ------------------------ | ----------------------------------------------------------------- |
| **Ежедневные тренды**    | Area chart с регистрациями по дням                                |
| **Период vs предыдущий** | Сравнение метрик текущего и прошлого периода с индикатором тренда |
| **Топ регистрации**      | Таблица самых результативных дней                                 |
| **Депозиты / траты**     | Раздельные суммы пополнений и покупок пользователей кампании      |

### Общая статистика

* Всего / активных / неактивных кампаний
* Суммарные регистрации
* Суммарные начисления баланса и подписок

## Управление (админ-панель)

### Создание кампании (пошагово)

1. **Название** (3-100 символов)
2. **Start параметр** (3-32 символа, `[A-Za-z0-9_-]`, уникальный)
3. **Тип бонуса** (4 варианта через инлайн-клавиатуру)
4. В зависимости от типа:
   * Balance: сумма в рублях
   * Subscription: дни, трафик, устройства, серверы
   * Tariff: выбор тарифа, длительность
   * None: сразу создаётся

### Действия

| Действие                 | Описание                                                |
| ------------------------ | ------------------------------------------------------- |
| **Статистика**           | Детальные метрики кампании                              |
| **Включить/Выключить**   | Переключение `is_active`                                |
| **Редактирование**       | Название, start параметр, параметры бонуса              |
| **Удаление**             | С подтверждением (заблокировано, если есть регистрации) |
| **Фильтр пользователей** | Просмотр пользователей, пришедших через кампанию        |

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

При переходе по ссылке кампании администратор получает уведомление с:

* Названием кампании и ID
* Информацией о пользователе
* Статусом (новый / уже зарегистрирован)
* Деталями бонуса

## Cabinet и Web API

### Cabinet Admin API

Полный CRUD: создание, просмотр, редактирование, удаление, переключение статуса. Дополнительно:

* Обзорная статистика (`GET /overview`)
* Детальная статистика (`GET /{id}/stats`)
* Данные для графиков (`GET /{id}/chart-data`) — ежедневные регистрации, тренды, период-vs-период, депозиты/траты
* Список зарегистрированных пользователей (`GET /{id}/registrations`)
* Доступные серверы, тарифы и партнёры для настройки

### Web API

CRUD через API-токен: `POST`, `GET`, `PATCH`, `DELETE`.

## Связанные переменные

Специальных переменных нет. Поведение зависит от:

| Переменная             | Описание                                             |
| ---------------------- | ---------------------------------------------------- |
| `DEFAULT_DEVICE_LIMIT` | Лимит устройств по умолчанию для subscription-бонуса |
| `MAX_DEVICES_LIMIT`    | Максимальный лимит устройств                         |
| `MINIAPP_CUSTOM_URL`   | Базовый URL для веб-ссылок кампаний                  |
| `BOT_USERNAME`         | Для генерации deep link (автоопределяется)           |