Модуль MLM (Партнеры, Рефералы, Комиссии, Ранги)

Обзор

Модуль MLM (Multi-Level Marketing) является основным бизнес-движком платформы IWM. Он управляет партнерской сетью, отслеживанием рефералов, расчетом комиссий, продвижением по рангам и обработкой выплат. Этот модуль реализует Дифференциальную Модель Комиссий с 7 типами дохода, где партнеры зарабатывают комиссии на основе разницы между своей ставкой ранга и ставкой нижестоящего партнера, с неограниченной глубиной.

Ключевые особенности

Характеристика	Описание
Модель комиссий	Дифференциальная (не Унилевел)
Глубина	Неограниченная
Типы дохода	7 (3 Активных + 3 Пассивных + 1 Лидерский Пул)
Основная валюта	USD
Ранги	21 (Консультант 0-11 с PRO вариантами)
Поддержание рангов	Бессрочные (ранги никогда не понижаются)

Зоны ответственности

• Регистрация партнеров и управление жизненным циклом
• Генерация реферальных ссылок и отслеживание атрибуции
• Управление структурой сетевого дерева (closure table)
• Квалификация и продвижение по рангам
• Расчет комиссий (дифференциальная модель)
• Обработка 7 типов дохода
• Распределение лидерских пулов
• Управление балансом (ожидающий, доступный)
• Обработка запросов на выплату

---

Доменные сущности

Partner

Центральная сущность, представляющая участника MLM сети.

Поле	Тип	Описание
id	UUID	Идентификатор партнера
user_id	UUID	Ссылка на core.users
sponsor_id	UUID	Прямой спонсор (вышестоящий партнер)
referral_code	VARCHAR(20)	Уникальный реферальный код
status	ENUM	Статус партнера
current_rank_id	UUID	Текущий ранг
highest_rank_id	UUID	Наивысший достигнутый ранг (совпадает с текущим - бессрочные)
direct_referrals_count	INT	Количество прямых рефералов
total_network_size	INT	Общий размер сети
tree_depth	INT	Глубина в дереве от корня
total_structure_turnover_usd	DECIMAL	Общий оборот структуры в USD
personal_turnover_usd	DECIMAL	Личный оборот в USD
is_activated	BOOLEAN	Совершена личная покупка на $1,100
joined_at	TIMESTAMP	Время регистрации
activated_at	TIMESTAMP	Время активации Ранга 1

PartnerTreePath

Closure table для эффективных запросов к дереву (неограниченная глубина).

Поле	Тип	Описание
ancestor_id	UUID	Вышестоящий партнер
descendant_id	UUID	Нижестоящий партнер
depth	INT	Расстояние между узлами

ReferralLink

Отслеживаемые реферальные ссылки для атрибуции.

Поле	Тип	Описание
id	UUID	Идентификатор ссылки
partner_id	UUID	Партнер-владелец
code	VARCHAR(20)	Уникальный код ссылки
name	VARCHAR(100)	Название ссылки (Instagram, YouTube)
target_url	VARCHAR(500)	Целевая страница
utm_source	VARCHAR(100)	UTM source параметр
utm_medium	VARCHAR(100)	UTM medium параметр
utm_campaign	VARCHAR(100)	UTM campaign параметр
clicks_count	INT	Всего кликов
registrations_count	INT	Регистраций по ссылке
conversions_count	INT	Конверсий (покупки/инвестиции)
is_active	BOOLEAN	Статус активности ссылки
expires_at	TIMESTAMP	Опциональное время истечения

ReferralAttribution

Отслеживает источник реферала для пользователей.

Поле	Тип	Описание
id	UUID	Идентификатор атрибуции
user_id	UUID	Приглашенный пользователь
partner_id	UUID	Приглашающий партнер
link_id	UUID	Исходная ссылка (опционально)
attribution_type	ENUM	FIRST_TOUCH или LAST_TOUCH
first_touch_at	TIMESTAMP	Первое взаимодействие
last_touch_at	TIMESTAMP	Последнее взаимодействие
converted_at	TIMESTAMP	Время конверсии
cookie_id	VARCHAR(100)	ID отслеживающей cookie

Rank

Определения рангов MLM (21-уровневая система).

Поле	Тип	Описание
id	UUID	Идентификатор ранга
code	VARCHAR(20)	Уникальный код (0, 1, 2, ..., 11, 4_PRO, ..., 11_PRO)
name	VARCHAR(100)	Отображаемое название (Консультант 0, Консультант 1 и т.д.)
level	INT	Уровень ранга (0-21)
is_pro	BOOLEAN	Флаг PRO варианта
turnover_requirement_usd	DECIMAL	Требуемый общий оборот структуры
personal_sales_rate	DECIMAL	Ставка для активного дохода (3%-20%)
entrance_fee_rate	DECIMAL	Ставка для комиссий со вступительных взносов (10.5%-20%)
passive_income_rate	DECIMAL	Ставка для пассивного дохода (0%-20%)
leadership_pool_eligible	BOOLEAN	Право на участие в лидерских пулах
description	TEXT	Описание ранга
badge_url	VARCHAR(500)	Изображение значка ранга
color_code	VARCHAR(20)	Цвет бренда
is_active	BOOLEAN	Ранг доступен

CommissionTransaction

Индивидуальная запись о комиссии с типом дохода.

Поле	Тип	Описание
id	UUID	Идентификатор транзакции
partner_id	UUID	Получающий партнер
income_type	ENUM	7 типов дохода
source_type	ENUM	ORDER, INVESTMENT, INVESTMENT_PROFIT, POOL_DISTRIBUTION
source_id	UUID	ID сущности-источника
source_partner_id	UUID	Партнер, инициировавший эту комиссию
own_rate	DECIMAL	Применимая ставка партнера
source_rate	DECIMAL	Ставка партнера-источника
differential_rate	DECIMAL	Разница между ставками
gross_amount_usd	DECIMAL	Сумма до вычетов
net_amount_usd	DECIMAL	Итоговая сумма
currency	VARCHAR(3)	Валюта (USD)
status	ENUM	Статус транзакции
period_id	VARCHAR(20)	Учетный период
idempotency_key	VARCHAR(255)	Предотвращение дубликатов

PartnerBalance

Финансовое состояние партнера в USD.

Поле	Тип	Описание
id	UUID	Идентификатор баланса
partner_id	UUID	Ссылка на партнера
available_balance_usd	DECIMAL	Сумма для вывода
pending_balance_usd	DECIMAL	Ожидает периода удержания
total_earned_usd	DECIMAL	Заработано за все время
total_withdrawn_usd	DECIMAL	Выведено за все время
income_personal_sales_usd	DECIMAL	Доход Типа 1 за все время
income_team_sales_usd	DECIMAL	Доход Типа 2 за все время
income_repeat_sales_usd	DECIMAL	Доход Типа 3 за все время
income_portfolio_returns_usd	DECIMAL	Доход Типа 4 за все время
income_client_profits_usd	DECIMAL	Доход Типа 5 за все время
income_network_profits_usd	DECIMAL	Доход Типа 6 за все время
income_leadership_pool_usd	DECIMAL	Доход Типа 7 за все время
currency	VARCHAR(3)	Валюта баланса (USD)
version	INT	Версия для оптимистичной блокировки
last_calculated_at	TIMESTAMP	Последний расчет комиссий

LeadershipPool

Конфигурация лидерского пула.

Поле	Тип	Описание
id	UUID	Идентификатор пула
pool_code	VARCHAR(20)	Уникальный код (POOL_5, POOL_6 и т.д.)
eligible_ranks	VARCHAR[]	Ранги, имеющие право на этот пул
percentage_of_turnover	DECIMAL	Процент от оборота компании
distribution_frequency	ENUM	WEEKLY или MONTHLY
qualification_volumes	JSONB	Требуемые объемы по рангам
is_active	BOOLEAN	Статус активности пула

PoolDistribution

Запись о событии распределения пула.

Поле	Тип	Описание
id	UUID	Идентификатор распределения
pool_id	UUID	Ссылка на лидерский пул
period_start	TIMESTAMP	Дата начала периода
period_end	TIMESTAMP	Дата окончания периода
total_turnover_usd	DECIMAL	Общий оборот компании
pool_amount_usd	DECIMAL	Общая сумма пула
qualified_participants	INT	Количество квалифицированных партнеров
per_person_amount_usd	DECIMAL	Сумма на участника
status	ENUM	PROCESSING, DISTRIBUTED
distributed_at	TIMESTAMP	Время завершения распределения

PayoutRequest

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

Поле	Тип	Описание
id	UUID	Идентификатор запроса
partner_id	UUID	Запрашивающий партнер
amount_usd	DECIMAL	Запрошенная сумма в USD
currency	VARCHAR(3)	Код валюты
payout_method_type	ENUM	BANK_CARD, BANK_TRANSFER, CRYPTO, EWALLET
payout_details	JSONB	Зашифрованная платежная информация
status	ENUM	Статус запроса
rejection_reason	TEXT	Причина отклонения
processed_by	UUID	Администратор, обработавший запрос
external_reference	VARCHAR(255)	Ссылка платежного провайдера

---

Жизненный цикл партнера

Процесс регистрации

Поток статусов партнера

Активация с Ранга 0 на Ранг 1

Переход с Ранга 0 на Ранг 1 открывает полный маркетинговый план:

Требование	Детали
Личная покупка	Минимальная личная покупка $1,100
Квалифицирующие продукты	Акции Si14 AG ИЛИ любой инвестиционный продукт
Открывает	Полный маркетинговый план со всеми 7 типами дохода

---

Реферальная система

Генерация ссылок

Партнеры могут создавать множество реферальных ссылок для разных каналов:

Отслеживание UTM параметров

Ссылки поддерживают полное UTM отслеживание:

Параметр	Пример	Назначение
utm_source	instagram	Источник трафика
utm_medium	social	Маркетинговый канал
utm_campaign	summer_2024	Идентификатор кампании

Атрибуция на основе cookie

Правила атрибуции:

• Время жизни cookie: 30 дней
• Тип атрибуции: Last-touch (побеждает последний реферер)
• Переопределение: Новый клик по реферальной ссылке обновляет атрибуцию
• Сохранение: Атрибуция фиксируется при конверсии (покупка/инвестиция)

---

Структура дерева

Паттерн Closure Table (Неограниченная глубина)

Партнерская сеть использует closure table для эффективных иерархических запросов с неограниченной глубиной:

Ключевые запросы

Получить прямых рефералов (Уровень 1):

SELECT descendant_id FROM partner_tree_paths
WHERE ancestor_id = :partner_id AND depth = 1

Получить всю нижестоящую сеть (Неограниченная глубина):

SELECT descendant_id, depth FROM partner_tree_paths
WHERE ancestor_id = :partner_id AND depth > 0
ORDER BY depth

Получить вышестоящую цепочку (Для дифференциальной комиссии):

SELECT
    p.id as partner_id,
    p.status,
    r.code as rank_code,
    r.personal_sales_rate,
    r.passive_income_rate,
    r.entrance_fee_rate,
    ptp.depth
FROM partner_tree_paths ptp
JOIN partners p ON p.id = ptp.ancestor_id
JOIN ranks r ON r.id = p.current_rank_id
WHERE ptp.descendant_id = :partner_id AND ptp.depth >= 1
ORDER BY ptp.depth ASC

---

Система рангов

21-уровневая иерархия рангов

Ставки комиссий по рангам

Ранг	Оборот ($)	Личные продажи	Вступительный взнос	Пассивный доход
0	0	3%	10.5%	0%
1	1,100	5%	11%	5%
2	10,000	8%	11.5%	8%
3	50,000	10%	12%	10%
4	100,000	12%	12.5%	12%
4_PRO	200,000	13%	13%	13%
5	400,000	14%	13.5%	14%
5_PRO	700,000	15%	14%	15%
6	1,000,000	16%	14.5%	16%
6_PRO	1,500,000	16.5%	15%	16.5%
7	2,000,000	17%	15.5%	17%
7_PRO	3,000,000	17.5%	16%	17.5%
8	5,000,000	18%	16.5%	18%
8_PRO	7,000,000	18.5%	17%	18.5%
9	10,000,000	19%	17.5%	19%
9_PRO	15,000,000	19.25%	18%	19.25%
10	25,000,000	19.5%	18.5%	19.5%
10_PRO	50,000,000	19.75%	19%	19.75%
11	100,000,000	20%	19.5%	20%
11_PRO	800,000,000	20%	20%	20%

Правила квалификации на ранг

Правило	Описание
Автоматическое продвижение	Ранги повышаются немедленно при достижении порога оборота
Бессрочные	Однажды достигнутые ранги никогда не истекают и не понижаются
Без поддержания	Нет ежемесячных требований по поддержанию
Мгновенные преимущества	Ставки комиссий применяются немедленно при изменении ранга

Ранг 0 vs Ранг 1+

Возможность	Ранг 0	Ранг 1+
Реферальная ссылка	Да	Да
Комиссия за личные продажи	3%	5%-20%
Командные продажи (дифференциальные)	Нет	Да
Пассивный доход	Нет	Да
Лидерские пулы	Нет	Ранг 5+

---

7 типов дохода

Обзор

Активный доход (Типы 1-3)

Тип	Название	Триггер	Расчет
1	Личные продажи	Прямая продажа своему клиенту	ставка_личных_продаж × сумма
2	Командные продажи	Нижестоящий партнер совершает продажу	Дифференциал от суммы продажи
3	Повторные продажи	Существующий клиент делает повторную покупку	Как Личные продажи

Пассивный доход (Типы 4-6)

Тип	Название	Триггер	Расчет
4	Доходы портфеля	Собственная инвестиция генерирует прибыль	Доходность по стратегии
5	Прибыль клиентов	Личный клиент получает прибыль	пассивная_ставка × прибыль_клиента
6	Прибыль сети	Клиент нижестоящего получает прибыль	Дифференциал от суммы прибыли

Лидерский доход (Тип 7)

Тип	Название	Триггер	Расчет
7	Лидерский пул	Еженедельное/ежемесячное распределение	Равная доля среди квалифицированных

---

Расчет комиссий

Дифференциальная модель комиссий

Основная формула для Командных продаж и Прибыли сети:

ЕСЛИ ранг_консультанта > ранг_партнера_источника:
    комиссия = (ставка_консультанта - ставка_источника) × сумма
ИНАЧЕ:
    комиссия = 0  // Нет комиссии при равном или меньшем ранге

Процесс дифференциального расчета

Пример комиссии

Сценарий: Партнер на Ранге 2 (ставка 8%) совершает продажу на $10,000

Вышестоящий партнер	Ранг	Ставка	Дифференциал	Комиссия
Партнер-источник	2	8%	Н/Д (Личные продажи)	$800
Прямой спонсор	4	12%	12% - 8% = 4%	$400
Уровень 2	5	14%	14% - 12% = 2%	$200
Уровень 3	6	16%	16% - 14% = 2%	$200
Уровень 4	6	16%	16% - 16% = 0%	$0
Уровень 5	11	20%	20% - 16% = 4%	$400
Уровень 6+	Любой	Любая	Весь остаток	$0 (достигнут максимум)

Всего распределено: $800 + $400 + $200 + $200 + $400 = $2,000 (20% от продажи)

Триггеры комиссий

Триггер	Тип источника	Типы дохода
Заказ выполнен	ORDER	Личные продажи, Командные продажи, Повторные продажи
Инвестиция активирована	INVESTMENT	Личные продажи (вступительный взнос), Командные продажи
Прибыль инвестиции	INVESTMENT_PROFIT	Прибыль клиентов, Прибыль сети
Распределение пула	POOL_DISTRIBUTION	Лидерский пул

Поток статусов комиссии

Статус	Описание	Влияние на баланс
PENDING	Рассчитана, ожидает период удержания	+ожидающий_баланс
APPROVED	Период удержания завершен	ожидающий → доступный
PAID	В доступном балансе партнера	Уже в доступном
REVERSED	Заказ возвращен до выплаты	-ожидающий_баланс
CLAWBACK	Заказ возвращен после выплаты	-доступный_баланс

---

Лидерские пулы

Конфигурация пулов

Пул	Допустимые ранги	% от оборота	Частота	Квалификация
POOL_5	5, 5_PRO	1%	Еженедельно	$5,000 / $10,000 недельный объём
POOL_6	6, 6_PRO	0.5%	Еженедельно	$20,000 / $30,000 недельный объём
POOL_7	7, 7_PRO	0.5%	Еженедельно	$45,000 / $60,000 недельный объём
POOL_8	8, 8_PRO	0.5%	Еженедельно	$90,000 / $120,000 недельный объём
POOL_9	9, 9_PRO	1%	Ежемесячно	Только достижение ранга
POOL_10	10, 10_PRO	1%	Ежемесячно	Только достижение ранга
POOL_11	11, 11_PRO	1%	Ежемесячно	Только достижение ранга

Примечание: Пулы 9-11 не требуют отдельного квалификационного объёма. Партнёры, достигшие и поддерживающие эти ранги, автоматически участвуют в ежемесячном распределении. Требование ранга по обороту ($10M-$800M) служит квалификационным порогом.

Правило 50% от ветки (только для пулов 5-8)

Ни одна ветка (прямая нижестоящая линия) не может вносить более 50% квалификационного объема:

Пример:
- Требуемая квалификация: $10,000
- Объем ветки A: $80,000 → засчитывается максимум $5,000 (лимит 50%)
- Объем ветки B: $15,000 → засчитывается $5,000+ (необходимый остаток)
- Результат: Квалифицирован (диверсифицированная структура)

Процесс распределения

---

Управление балансом

Типы баланса

Период удержания по источнику

Тип источника	Период удержания	Причина
Заказ продукта	14 дней	Окно возврата/обмена
Инвестиция	7 дней	Верификация средств
Пассивный доход	7 дней	Подтверждение прибыли
Лидерский пул	0 дней	Немедленно при распределении

Разбивка дохода

Баланс отслеживает заработок по типам дохода:

Поле	Тип дохода
income_personal_sales_usd	Тип 1: Личные продажи
income_team_sales_usd	Тип 2: Командные продажи
income_repeat_sales_usd	Тип 3: Повторные продажи
income_portfolio_returns_usd	Тип 4: Доходы портфеля
income_client_profits_usd	Тип 5: Прибыль клиентов
income_network_profits_usd	Тип 6: Прибыль сети
income_leadership_pool_usd	Тип 7: Лидерский пул

Безопасность параллелизма

Операции с балансом используют оптимистичную блокировку с номерами версий:

// Пример: Обновление баланса с проверкой версии
const result = await tx.partnerBalance.update({
  where: {
    partnerId: partner.id,
    version: expectedVersion,
  },
  data: {
    pendingBalanceUsd: { increment: amount },
    version: { increment: 1 },
    updatedAt: new Date(),
  },
});

---

Система выплат

Процесс запроса выплаты

Правила выплат

1. Минимальная сумма: Минимальный вывод $100 USD
2. Один ожидающий: Только один ожидающий запрос на партнера
3. Требуется KYC: Требуется уровень STANDARD KYC
4. Списание баланса: Сумма списывается сразу при запросе
5. Возврат при ошибке: Баланс восстанавливается при неудачном платеже
6. Статус партнера: Должен быть ACTIVE для запроса выплаты

Методы выплат

Метод	Провайдер	Время обработки
Банковская карта	Stripe/YooKassa	1-3 рабочих дня
Банковский перевод	Вручную	3-5 рабочих дней
Криптовалюта	Различные	В тот же день
Электронный кошелек	Различные	В тот же день

---

Публикуемые события

Событие	Триггер	Payload
PartnerRegistered	Создан новый партнер	partnerId, userId, sponsorId
PartnerActivated	Покупка на $1,100 (Ранг 0→1)	partnerId, activationType
PartnerStatusChanged	Переход статуса	partnerId, fromStatus, toStatus
ReferralLinkCreated	Создана новая ссылка	linkId, partnerId, code
ReferralLinkClicked	Переход по ссылке	linkId, partnerId, visitorInfo
ReferralAttributed	Пользователь привязан к партнеру	userId, partnerId, linkId
CommissionCalculated	Создана комиссия	transactionId, partnerId, incomeType, amount
CommissionApproved	Период удержания завершен	transactionId, partnerId, amount
CommissionPaid	Комиссия переведена в доступный	transactionId, partnerId, amount
CommissionReversed	Комиссия отменена	transactionId, partnerId, reason
BalanceUpdated	Изменение баланса	partnerId, type, amount, newBalance
PayoutRequested	Подан запрос на выплату	payoutId, partnerId, amount
PayoutApproved	Выплата одобрена	payoutId, partnerId
PayoutCompleted	Выплата обработана	payoutId, partnerId, reference
PayoutRejected	Выплата отклонена	payoutId, partnerId, reason
RankChanged	Повышение ранга	partnerId, fromRank, toRank
PoolDistributed	Лидерский пул выплачен	poolId, amount, participants

---

Потребляемые события

Событие	Источник	Обработчик
UserRegistered	Core	Создать партнера, если есть реферальный код
OrderCompleted	Commerce	Рассчитать Личные/Командные/Повторные продажи
OrderRefunded	Commerce	Отменить комиссии
InvestmentActivated	Investment	Рассчитать комиссии со вступительного взноса
InvestmentProfitDistributed	Investment	Рассчитать Прибыль клиентов/сети

---

Бизнес-правила и инварианты

Правила партнеров

1. Один партнер на пользователя (связь 1:1)
2. Партнер не может быть своим спонсором
3. Спонсор не может быть изменен после регистрации
4. Только партнеры со статусом ACTIVE получают комиссии
5. Партнеры со статусом TERMINATED не могут быть реактивированы
6. Все партнеры начинают с Ранга 0

Правила комиссий

1. Комиссии рассчитываются только для вышестоящих со статусом ACTIVE
2. Неограниченная глубина для дифференциальных комиссий
3. Дифференциал останавливается при достижении ставки 20%
4. Ключ идемпотентности предотвращает дублирование комиссий
5. Отмена/возврат источника отменяет все связанные комиссии
6. Распределения лидерских пулов немедленные (без периода удержания)

Правила рангов

1. Ранги бессрочные (никогда не понижаются)
2. Продвижение по рангам автоматическое при достижении порога оборота
3. Ранг 0→1 требует личной покупки на $1,100
4. Все последующие ранги квалифицируются по Общему обороту структуры
5. Ставки комиссий применяются немедленно при изменении ранга

Правила баланса

1. Доступный баланс не может быть отрицательным
2. Ожидающий баланс не может быть отрицательным
3. Версия должна совпадать для обновления (оптимистичная блокировка)
4. Всего заработано >= всего выведено + доступный + ожидающий

Правила выплат

1. Только один ожидающий/обрабатываемый запрос на партнера
2. Минимальный вывод: $100 USD
3. Требуется верификация KYC
4. Партнер должен быть в статусе ACTIVE для запроса выплаты

---

Точки интеграции

Предоставляет другим модулям

Интерфейс	Потребители	Назначение
IPartnerLookupService	Commerce, Investment	Получить партнера по реферальному коду
ICommissionService	Commerce, Investment	Запустить расчет комиссий
IAttributionService	Commerce, Investment	Получить реферальную атрибуцию для пользователя
IPassiveIncomeService	Investment	Запустить расчет прибыли клиентов/сети

Потребляет от других модулей

Интерфейс	Провайдер	Назначение
IUserLookupService	Core	Получить данные профиля пользователя
IKycStatusService	Core	Проверить уровень KYC для выплат
IInvestmentProfitService	Investment	Получить данные о прибыли для пассивного дохода

---

Связанные документы

• Схема MLM
• Реализация дерева MLM
• Движок комиссий
• Правила комиссий
• Правила рангов
• Правила выплат
• Архитектура модулей