Архитектура affiliate-модуля под Obmenka CRM

Источник: Plan агент с чтением existing code, 2026-05-16

TL;DR

1. Новый домен Affiliate — отдельный тип пользователя с ref-кодом и USDT-балансом
2. Client.referrer_affiliate_id — denorm указатель, client_affiliations — audit history
3. commission_entries: одна запись на (deal_id, affiliate_id, tier), UNIQUE для идемпотентности
4. Multi-level через parent_affiliate_id (≤ 3 уровня) + denorm tier2/3_parent_id
5. Trigger расчёта = переход Deal.status → done (в той же транзакции что сделка)
6. Lifecycle: pending → available (после hold) → paid (через payout_request → operation)
7. RBAC новая роль affiliate с отдельным layout aff_base.html
8. MVP = single-level, плоская комиссия, ручные выплаты

Модель данных

Новые таблицы

• affiliate_programs (id, code, name, base_model, tier1/2/3_pct, hold_days, min_payout, attribution_mode...)
• affiliates (id, user_id, external_ref, parent_affiliate_id, tier2/3_parent_id denorm, override ставки, payout_method, status)
• ref_codes (id, affiliate_id, code, label, clicks/signups/deals counters)
• client_affiliations (id, client_id, affiliate_id, ref_code_id, source, attached_at, detached_at) — partial UNIQUE на одну активную
• commission_entries (id, deal_id, affiliate_id, tier, program_id, base_value_usdt, rate_pct, amount_usdt, status, available_at, paid_at, reverses_entry_id) — UNIQUE(deal_id, affiliate_id, tier)
• payout_requests (id, affiliate_id, amount, status, payout_op_id, matched_raw_tx_id)

Изменения

• clients: +referrer_affiliate_id, +referrer_ref_code_id, +referrer_set_at
• deals: +affiliate_snapshot_id, +commission_calculated_at
• users: +totp_secret, +totp_enabled, +affiliate_id
• roles: новая запись affiliate

Альтернативы отвергнуты

• Materialized view — у комиссий lifecycle, нужны транзакции
• Граф через CTE без denorm — не работает CHECK от циклов
• Только history без denorm referrer — будет JOIN на каждом списке

Алгоритм расчёта

def accrue_for_deal(deal):
    if not deal.client.referrer_affiliate_id: return
    aff = load(referrer_affiliate_id)
    if aff.status != 'active': return
    caff = active_affiliation(deal.client_id)
    if caff.expires_at and deal.occurred_at > caff.expires_at: return
    if caff.attribution_mode == 'first_deal_only' and deals_count > 1: return

    base = compute_base(deal, program.base_model)  # volume/profit/fixed/hybrid

    # Tier 1
    rate1 = aff.override_tier1_pct or program.tier1_pct
    amt1 = base * rate1 + program.fixed_usdt_per_deal
    if program.max_commission_per_deal_usdt: amt1 = min(amt1, ...)
    upsert(deal_id, aff.id, tier=1, amount=amt1)

    # Tier 2 (если parent есть)
    # Tier 3 (если tier3_parent_id есть)

    deal.affiliate_snapshot_id = aff.id

Edge cases

• aff.blocked → не начисляем, upline тоже молчит (анти-invite-fraud)
• cancel deal → reverse_entry с -amount
• recalc после edit → admin-only command, voidает pending + считает заново
• перепривязка клиента → старые комиссии за старым партнёром (snapshot)
• self-referral → check tg_username/phone match → void
• cycle в parent → защищено CHECK + BFS при назначении

Tracking

3 пути привязки клиента к партнёру: 1. Через ссылку /r/{code} → cookie 30 дней → при создании Client 2. Manual менеджером в карточке клиента 3. Self-claim через TG-бот (фаза 3)

/r/{code} — публичный endpoint, инкремент counter, signed cookie через URLSafeTimedSerializer, 302 на main page.

Перепривязка: detached_at = now() на старой, новая активная. Старые комиссии не трогаются.

Lifecycle комиссии и выплат

accrue → pending
   ↓ (hold_days)
available
   ↓ partner requests payout, admin approves
paid (linked to Operation crypto_out)
   ↓ reconcile.py связывает с raw_blockchain_tx
matched_raw_tx_id заполнен

Балансы партнёра = SUM(amount) WHERE status='pending'/'available'/'paid'.

Hold-cron каждый час: pending → available WHERE created_at + hold_days <= NOW() AND NOT (deal status cancelled).

RBAC

Privacy: партнёр НЕ видит ФИО/телефон клиентов, только external_ref C-XXXX + агрегаты.

2FA: TOTP в фазе 7.2 (опц на MVP, обязательно для production-выхода).

API endpoints

Публичные: - GET /r/{code} — tracking redirect

Партнёрский кабинет (/aff/*, требует role=affiliate): - Dashboard, links, clients, earnings, payouts, settings

Админ (/affiliates/*, /affiliate-programs/*, /payouts/*): - CRUD affiliates, programs, attach клиента, approve payouts, void/recalc commission

Internal jobs: - python -m app.jobs.commission_release (hourly) - python -m app.jobs.commission_payout_auto (фаза 2)

UI

Админ — под существующим сайдбаром, новая группа «Партнёры»: - /affiliates — список - /affiliates/{id} — карточка с tabs (обзор/клиенты/комиссии/выплаты/даунлайн/настройки) - /affiliate-programs — программы - /payouts — pending выплаты

Изменения существующих: - client_card.html — блок «Привязка к партнёру» - clients_list.html — колонка «Партнёр» - deal_card.html — блок «Комиссии партнёрам» - dashboard.html — виджет аффилиатной программы

Партнёрский кабинет — отдельный layout aff_base.html (отличается визуально): - /aff дашборд - /aff/links мои ссылки - /aff/clients мои клиенты (псевдонимизированно) - /aff/earnings заработок (с экспортом CSV) - /aff/payouts выплаты - /aff/settings

Фазы

E7.1 MVP (3–4 нед)

• Миграция таблиц
• 1 модель: volume_usdt с фиксированным %
• БЕЗ multi-level
• attribution = lifetime
• Кабинет (без 2FA)
• Tracking /r/{code} + cookie + auto-attach
• Manual attach менеджером
• Accrual в deal_change_status и deal_new_post
• Hold-cron
• Admin: CRUD + approve payouts

E7.2 (2–3 нед)

• Multi-level + tier2/3
• Override-ставки
• attribution_mode варианты
• Auto payout по threshold
• Scheduled payouts
• 2FA TOTP
• Anti-self-referral
• UI дерево даунлайна

E7.3 (отложено)

• Smart-contract выплаты
• ML/rule fraud detection
• Отдельный subdomain partners.obmenka...
• Webhooks партнёрам
• A/B-тесты программ
• Tax reporting

Риски

1. Цикл parent_affiliate_id → защита: CHECK + BFS при назначении + MAX_TIER_DEPTH константа
2. Hold-cron падение → APScheduler мониторинг + admin страница «холд должен был истечь»
3. Race при accrue → UNIQUE (deal_id, affiliate_id, tier) защищает
4. Изменение ставки задним числом → snapshot ставки в commission_entries → не меняется
5. Cancel после выплаты → reverse-entry с negative, баланс уйдёт в минус, ручной разбор

Производительность

При 150 сделок/мес = 5 в день → ms. Реалистичный max 10k/мес = 30k entries/год — все запросы покрыты индексами: - (affiliate_id, status) для балансов - (deal_id) для лукапа - partial available_at WHERE status='pending' для cron - clients.referrer_affiliate_id для списка клиентов партнёра

Чего НЕ делаем в E7.1