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

# Реферальная программа

> Партнёрская система с комиссиями, выводом средств и аналитикой

## Обзор

Реферальная программа позволяет пользователям приглашать новых клиентов и зарабатывать комиссию с их пополнений и покупок. Включает партнёрскую систему для профессиональных рефереров.

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

При отключении:

* Кнопки "Партнёрка", "Мои рефералы" скрываются из меню
* Административные функции остаются доступными

## Механика работы

### Реферальная ссылка

Каждый пользователь получает уникальный реферальный код формата `refAbC12dEf` (3 + 8 символов) и ссылку:

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

### Процесс приглашения

1. Реферер делится ссылкой или QR-кодом
2. Новый пользователь переходит по ссылке и регистрируется
3. Создаётся запись `referral_registration_pending`
4. При первом пополнении (>= `REFERRAL_MINIMUM_TOPUP_KOPEKS`) обоим начисляются бонусы
5. С каждого последующего пополнения и покупки реферала начисляется комиссия

### QR-код

* Генерируется через библиотеку `qrcode`
* Содержит полную реферальную ссылку
* Кэшируется в `data/referral_qr/{user_id}.png`
* Доступен через кнопку "Показать QR-код"

## Система комиссий

### Бонус за первое пополнение

При первом пополнении реферала на сумму >= `REFERRAL_MINIMUM_TOPUP_KOPEKS`:

| Получатель                       | Бонус                                           |
| -------------------------------- | ----------------------------------------------- |
| **Реферал** (новый пользователь) | `REFERRAL_FIRST_TOPUP_BONUS_KOPEKS` на баланс   |
| **Реферер** (пригласивший)       | `max(REFERRAL_INVITER_BONUS_KOPEKS, комиссия%)` |

Если пополнение меньше минимума — реферер получает только комиссию, бонус за первое пополнение откладывается.

<Note>
  Если `REFERRAL_FIRST_TOPUP_BONUS_KOPEKS = 0`, информация о бонусе для реферала скрывается из уведомлений и личного кабинета. Аналогично, если `REFERRAL_INVITER_BONUS_KOPEKS = 0`, карточка бонуса реферера не отображается в интерфейсе.
</Note>

### Комиссия с пополнений

С **каждого** пополнения реферала (включая первое и последующие):

```
Комиссия = сумма_пополнения × REFERRAL_COMMISSION_PERCENT / 100
```

Если `REFERRAL_MAX_COMMISSION_PAYMENTS` > 0, комиссия начисляется только с первых N пополнений каждого реферала. После достижения лимита комиссия с пополнений этого реферала больше не начисляется. По умолчанию значение `0` — комиссия начисляется с каждого пополнения без ограничений.

### Комиссия с покупок

С каждой покупки подписки:

```
Комиссия = сумма_покупки × REFERRAL_COMMISSION_PERCENT / 100
```

### Индивидуальная комиссия

Администратор может установить персональный процент комиссии для конкретного пользователя (`User.referral_commission_percent`). Это переопределяет глобальный `REFERRAL_COMMISSION_PERCENT`.

## Интерфейс пользователя

### Меню "Партнёрка"

| Кнопка              | Описание                                                |
| ------------------- | ------------------------------------------------------- |
| Создать приглашение | Сформировать текст для пересылки с кнопкой "Поделиться" |
| QR-код              | Показать QR с реферальной ссылкой                       |
| Список рефералов    | Пагинированный список (10 на страницу) с деталями       |
| Аналитика           | Доходы по периодам и топ рефералов                      |
| Запросить вывод     | Заявка на вывод средств (если включено)                 |

### Список рефералов

Для каждого реферала показывается:

* Статус (активный/неактивный)
* Первое пополнение (да/нет)
* Количество пополнений
* Заработано с реферала
* Дата регистрации
* Последняя активность

### Аналитика

* Доходы по периодам: сегодня, неделя, месяц, квартал
* Топ-5 самых прибыльных рефералов

## Вывод средств

### Включение

```env theme={null}
REFERRAL_WITHDRAWAL_ENABLED=true
REFERRAL_WITHDRAWAL_MIN_AMOUNT_KOPEKS=50000    # 500 руб
REFERRAL_WITHDRAWAL_COOLDOWN_DAYS=30
```

### Пользовательский flow

1. Проверка доступности: включён ли вывод, достаточно ли средств, прошёл ли cooldown
2. Ввод суммы (ручной или "Вывести всё")
3. Ввод реквизитов (номер СБП и банк, мин. 10 символов)
4. Подтверждение заявки
5. Система создаёт заявку с анализом рисков и уведомляет администраторов

### Расчёт доступного баланса

Если `REFERRAL_WITHDRAWAL_ONLY_REFERRAL_BALANCE=true` (по умолчанию):

* Доступны только реферальные доходы
* Формула: `min(баланс, заработано - выведено - в ожидании)`
* Собственные пополнения не учитываются

Если `false`:

* Доступен весь оставшийся баланс пользователя

### Статусы заявки

| Статус      | Описание                         |
| ----------- | -------------------------------- |
| `pending`   | Ожидает проверки администратором |
| `approved`  | Одобрена, баланс списан          |
| `rejected`  | Отклонена                        |
| `completed` | Деньги переведены                |
| `cancelled` | Отменена пользователем           |

### Анализ подозрительной активности

Каждая заявка автоматически проверяется на признаки фрода (risk score 0-100):

| Проверка                              | Баллы | Описание                                    |
| ------------------------------------- | ----- | ------------------------------------------- |
| Пополнения без покупок                | +40   | Средства не тратились на подписки           |
| Пополнения >> траты                   | +25   | Соотношение пополнений к тратам > порога    |
| Нет рефералов, но есть доход          | +50   | Реферальный доход без фактических рефералов |
| Много пополнений от одного реферала   | +15   | Превышение порога за месяц                  |
| Крупные пополнения от одного реферала | +10   | Превышение минимальной суммы                |
| Весь доход от одного реферала         | +20   | Только один платящий реферал (>500 руб)     |
| Много начислений за неделю            | +15   | >20 начислений за последнюю неделю          |

**Уровни риска:**

| Диапазон | Уровень               | Рекомендация            |
| -------- | --------------------- | ----------------------- |
| 0-29     | Низкий (зелёный)      | Можно одобрить          |
| 30-49    | Средний (жёлтый)      | Рекомендуется проверка  |
| 50-69    | Высокий (оранжевый)   | Требует проверки        |
| 70-100   | Критический (красный) | Рекомендуется отклонить |

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

1. Список ожидающих заявок с цветовым кодированием риска
2. **Одобрить** → баланс списывается, создаётся транзакция `withdrawal`, пользователь уведомлён
3. **Отклонить** → пользователь уведомлён
4. **Отметить "Переведено"** → статус `completed`, пользователь уведомлён

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

### Подача заявки

Через Cabinet API пользователь подаёт заявку на партнёрство:

* Название компании (опционально)
* URL сайта (опционально)
* Telegram-канал (опционально)
* Описание деятельности (опционально)
* Ожидаемое количество рефералов в месяц (опционально)
* Желаемый процент комиссии 1-100% (опционально) — отображается администратору при рассмотрении заявки

### Статусы партнёра

| Статус     | Описание               |
| ---------- | ---------------------- |
| `none`     | Не подавал заявку      |
| `pending`  | Заявка на рассмотрении |
| `approved` | Одобрен                |
| `rejected` | Отклонён               |

### Одобрение партнёра

При одобрении администратор устанавливает:

* **Персональный процент комиссии** (переопределяет глобальный)
* Генерируется реферальный код (если отсутствует)
* Пользователь уведомляется

### Возможности партнёра

* Персональный процент комиссии
* Привязка [рекламных кампаний](/bot/campaigns) — переходы по кампании автоматически делают партнёра реферером
* Детальная статистика: рефералы, конверсии, доходы по периодам
* Аналитика трендов (сравнение текущего и предыдущего периодов)

### Управление партнёрами (админ)

| Действие                    | Описание                                                 |
| --------------------------- | -------------------------------------------------------- |
| Одобрить заявку             | С установкой комиссии                                    |
| Отклонить                   | С комментарием                                           |
| Отозвать статус             | Удаление партнёрства, очистка комиссии, отвязка кампаний |
| Изменить комиссию           | Обновление процента                                      |
| Привязать/отвязать кампанию | Управление связью партнёр-кампания                       |

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

| Событие                          | Получатель     | Описание                        |
| -------------------------------- | -------------- | ------------------------------- |
| Регистрация по ссылке            | Реферал        | Welcome + бонусы                |
| Регистрация по ссылке            | Реферер        | "Новый реферал" + комиссия      |
| Бонус за первое пополнение       | Реферал        | "Бонус получен!"                |
| Награда за первое пополнение     | Реферер        | "Награда!" + сумма + комиссия   |
| Комиссия с пополнения            | Реферер        | "Реферальная комиссия!" + сумма |
| Комиссия с покупки               | Реферер        | "Комиссия с покупки!" + сумма   |
| Заявка на вывод                  | Администраторы | Детали + анализ рисков          |
| Вывод одобрен/отклонён/переведён | Пользователь   | Статус заявки                   |

```env theme={null}
REFERRAL_NOTIFICATIONS_ENABLED=true
REFERRAL_NOTIFICATION_RETRY_ATTEMPTS=3
```

## Реферальные конкурсы

Подробнее в разделе [Конкурсы и игры](/bot/contests#реферальные-конкурсы).

## Диагностика (админ)

* Анализ логов для поиска "потерянных" рефералов (кликнул ссылку, но реферер не записался)
* Аудит БД на пропущенные бонусы
* Предпросмотр и применение исправлений
* Синхронизация с реферальными конкурсами

## Настройка

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

| Переменная                          | По умолчанию | Описание                                                                                    |
| ----------------------------------- | ------------ | ------------------------------------------------------------------------------------------- |
| `REFERRAL_PROGRAM_ENABLED`          | `true`       | Глобальный переключатель                                                                    |
| `REFERRAL_COMMISSION_PERCENT`       | `25`         | Процент комиссии (по умолчанию)                                                             |
| `REFERRAL_MINIMUM_TOPUP_KOPEKS`     | `10000`      | Минимум для первого пополнения (100 руб)                                                    |
| `REFERRAL_FIRST_TOPUP_BONUS_KOPEKS` | `10000`      | Бонус рефералу (100 руб)                                                                    |
| `REFERRAL_INVITER_BONUS_KOPEKS`     | `10000`      | Мин. бонус рефереру (100 руб)                                                               |
| `REFERRAL_MAX_COMMISSION_PAYMENTS`  | `0`          | Максимальное количество пополнений реферала, с которых начисляется комиссия. 0 = без лимита |
| `SKIP_REFERRAL_CODE`                | `false`      | Пропуск ввода реферального кода при регистрации                                             |

### Вывод средств

| Переменная                                   | По умолчанию | Описание                                               |
| -------------------------------------------- | ------------ | ------------------------------------------------------ |
| `REFERRAL_WITHDRAWAL_ENABLED`                | `false`      | Включить вывод                                         |
| `REFERRAL_WITHDRAWAL_MIN_AMOUNT_KOPEKS`      | `50000`      | Минимум вывода (500 руб)                               |
| `REFERRAL_WITHDRAWAL_COOLDOWN_DAYS`          | `30`         | Cooldown между заявками (дни)                          |
| `REFERRAL_WITHDRAWAL_ONLY_REFERRAL_BALANCE`  | `true`       | Только реферальный баланс                              |
| `REFERRAL_WITHDRAWAL_REQUISITES_TEXT`        | —            | Подсказка для поля реквизитов                          |
| `REFERRAL_WITHDRAWAL_NOTIFICATIONS_TOPIC_ID` | `0`          | Топик для уведомлений (0 = основной чат)               |
| `REFERRAL_WITHDRAWAL_TEST_MODE`              | `false`      | Тестовый режим (пропуск cooldown, тестовые начисления) |

### Пороги подозрительной активности

| Переменная                                              | По умолчанию | Описание                                    |
| ------------------------------------------------------- | ------------ | ------------------------------------------- |
| `REFERRAL_WITHDRAWAL_SUSPICIOUS_MIN_DEPOSIT_KOPEKS`     | `100000`     | Порог суммы от одного реферала (1000 руб)   |
| `REFERRAL_WITHDRAWAL_SUSPICIOUS_MAX_DEPOSITS_PER_MONTH` | `10`         | Макс. пополнений от одного реферала в месяц |
| `REFERRAL_WITHDRAWAL_SUSPICIOUS_NO_PURCHASES_RATIO`     | `3`          | Соотношение пополнений к тратам             |

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

| Переменная                         | По умолчанию | Описание                                |
| ---------------------------------- | ------------ | --------------------------------------- |
| `REFERRAL_PARTNER_SECTION_VISIBLE` | `true`       | Показывать раздел партнёрства в Cabinet |