> ## 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`, карточка бонуса реферера не отображается в интерфейсе.

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

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

```
Комиссия = сумма_пополнения × 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.md) — переходы по кампании автоматически делают партнёра реферером
* Детальная статистика: рефералы, конверсии, доходы по периодам
* Аналитика трендов (сравнение текущего и предыдущего периодов)

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

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

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

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

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

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

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

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

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

## Настройка

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

| Переменная | По умолчанию | Описание |
| - | - | - |
| `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 |


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