PRD v2: Affiliate-программа Obmenka

Версия: 2.0 (финальная для согласования) Дата: 2026-05-16 Автор: AI assistant Основано на: - 3 deep-research отчётах: docs/affiliate-research/01-crypto-exchanges.md, 02-adjacent-industries.md, 03-architecture-plan.md - PRD v1: docs/affiliate-prd-v1.md - Критика v1: docs/affiliate-prd-v1-critique.md (19 правок применены)

1. Executive Summary (1 страница для руководителя)

Что делаем

Модуль партнёрской программы внутри CRM Obmenka. Партнёры (блогеры, TG-каналы) приводят клиентов и получают комиссию USDT с каждой их сделки.

Базовая экономика

• Default ставка: 0.3% от объёма сделки в USDT-эквиваленте (≈30% от типичной нашей маржи 1%)
• Привязка: 24 месяца после первой сделки клиента
• Min выплата: 50 USDT, hold 7 дней, payout USDT-TRC20
• Network fee удерживаем с партнёра (~1.5 USDT/выплата)

Critical compliance (TR)

• MVP запускаем ТОЛЬКО для не-турецких партнёров и не-турецкой аудитории (русско/англо/немецкоязычные TG)
• До получения CMB-лицензии или ясности с регулятором — без публичной TR-страницы
• При TR-резиденте партнёре удерживаем 1% withholding tax (закон с 2025)

Финансовая модель (6 мес)

Сроки

• E7.1 MVP: 3–4 недели (single-level, manual everything)
• E7.2 расширение: 2–3 недели (multi-level + 2FA + auto-payouts)

KPI (реалистичные)

• 3 мес: 5 партнёров, 5–8% сделок через них
• 6 мес: 15 партнёров, 10–15% сделок через них
• 12 мес: 20–25% сделок через них

2. Бизнес-цель и контекст

Проблема

Прямая реклама в Анталье в туристический сезон даёт CAC $30–100/клиент. Партнёрка платит только за результат — % от уже принесённого профита.

Текущий стейт

После E1–E6 у нас рабочая CRM с реальными сделками (151 в seed, 624 on-chain транзакции, 3 отделения в Анталье + онлайн). Партнёрка — естественное расширение.

Конкурентный контекст

• BestChange (агрегатор обменников): 30% Level 1 + 10% Level 2, lifetime, min $1
• Bybit: 30–50% от fee + 10% sub-override, daily payouts
• Coinsfera (прямой конкурент в Стамбуле): partner есть, условия закрыты
• Binance: закрыл TR retail referral в окт 2024 из-за MASAK ⚠

Уроки: TR-фактор важен. Платить от объёма прозрачнее чем от profit.

3. Модель вознаграждения

3.1. Default-модель (E7.1)

commission = deal.volume_usdt × 0.003
commission_capped = min(commission, deal.profit_usdt × 0.5)

где volume_usdt = FX_to_USDT[give_asset] × give_amount.

Объяснение для партнёра: «Вы получаете 0.3% с каждого USDT-эквивалента приведённого клиента».

Почему 0.3% от volume, не 30% от profit: - Прозрачно: партнёр заранее знает свою комиссию - Стандарт индустрии (BestChange, ChangeNOW, SimpleSwap — все от volume/fee) - При типичной марже 1% даёт нам ~70% профита, партнёру ~30% - Защита: cap ≤ 50% profit — если markup случайно 0.2%, не платим больше 50% от того что заработали

3.2. Опциональные программы

Программа задаётся при создании партнёра, может меняться admin'ом. Изменение применяется только к будущим сделкам.

3.3. Multi-level (только E7.2)

НЕТ Tier 3 — даже в фазе 2. Это пирамида.

3.4. Tier-бонусы по объёму (E7.2)

• Upgrade — мгновенно с следующей сделки
• Downgrade — с protection period 2 месяца (Binance-стиль)
• Cron 1-го числа каждого месяца переоценивает

3.5. Исключения

• Сделки в excluded_assets программы (например, RUB/UAH могут быть исключены если admin решит) → 0
• Cancelled сделки → 0
• Internal transfers → 0
• Self-referral (по passport-match KYC) → voided + alert
• Минимум на сделку отсутствует (приветствуем мелкого туриста)

4. Tracking и привязка клиента

4.1. Три канала привязки

1. Через ссылку /r/{code} (онлайн) - Cookie obm_ref (signed, 30 дней) — действует до первой сделки клиента - После первой сделки — привязка lifetime в рамках attribution-окна (см. 4.2) - Endpoint без auth, инкрементит ref_codes.clicks_count

2. Manual ввод кассиром/менеджером (офлайн в Лиман/Лара) - В форме новой сделки и в карточке клиента — поле «Реф-код» (autocomplete) - Кассир вводит код с визитки/QR клиента → привязка source='manual' - Если клиент перепривязан — требует reason (логируется)

3. Self-claim в TG-боте (фаза 3, не в E7.1)

4.2. Окно attribution

Default (E7.1): 24 месяца с момента первой сделки клиента (после — клиент «отвязывается», комиссий нет, но привязка остаётся в audit для отчётов).

Опция «lifetime»: в индивидуальной программе для VIP-партнёров (по контракту).

4.3. Перепривязка

• Менеджер может переключить клиента на другого партнёра (требует reason)
• Старая запись client_affiliations.detached_at = now()
• Старые комиссии не трогаются (snapshot в commission_entries)
• Новые сделки идут новому партнёру
• Если конфликт «cookie ставит A, manager хочет B» → требуется admin-approval

4.4. Opt-out клиента

В карточке клиента — кнопка «Отвязать от партнёра» (admin/manager) с reason. Старые комиссии остаются, новые сделки — без партнёра. Партнёру причину не разглашаем.

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

5.1. Состояния

[Deal → done]
       ↓ (post-commit hook, eventual consistency)
  pending
       ↓ (hold_days=7, cron-daily 04:00 UTC)
  available
       ↓ (partner запросил payout → admin approve)
  paid

Альтернативы: - voided — self-referral, asset excluded, аффилиат blocked - reversed — отмена сделки после paid (баланс уходит в минус, см. 5.4)

5.2. Hold (7 дней default)

• Cron-job раз в сутки (04:00 UTC, после backup и tron-sync)
• Переводит pending → available при условиях: hold истёк И сделка не cancelled

5.3. Выплаты

Триггер MVP: manual — партнёр сам в кабинете запрашивает.

Условия: - balance_available ≥ 50 USDT (минимум default-программы) - affiliate.status = active - KYC партнёра пройден (для физлица: имя + tax-ID + payout-address screening)

TRC20 network fee: - Удерживается с партнёра (default), ~1.5 USDT/выплата - В UI кабинета: «Запрос 50 USDT − 1.5 USDT (network fee) = 48.5 USDT к получению» - Прозрачно показывается до подтверждения

Withholding tax 1% (для TR-резидентов): - Удерживаем дополнительно при выплате - В UI: «50 USDT − 1.5 fee − 0.5 TR withholding = 48.0 USDT» - Раз в месяц admin/accountant выгружает отчёт по удержаниям для бухгалтерии

Approval flow: 1. Партнёр → POST /aff/payouts/request → payout_request(status=pending) 2. Admin видит в /payouts, проверяет аномалии (новый адрес, большая сумма) 3. Admin делает USDT-TRC20 перевод (из hot wallet, вручную или через signer) 4. Admin вводит tx_hash реальной транзакции в форму approve 5. Создаётся Operation(op_type='payout', source='payout') — отдельный source, не от Deal 6. payout_request.status='paid', все связанные commission_entries → paid 7. reconcile.py через час найдёт on-chain tx и свяжет payout_request.matched_raw_tx_id

5.4. Refund / reverse сценарий

При отмене сделки уже после выплаты: - Создаётся reverse_entry(amount = -original) - Если у партнёра есть available > |amount| → списываем оттуда - Если нет — балансу разрешено быть отрицательным - При следующем accrual — новые комиссии в первую очередь покрывают минус - Если партнёр стал inactive и баланс остался в минусе — списываем убыток (логируется как commission_writeoff)

6. Anti-fraud

6.1. Обязательный минимум (E7.1)

6.2. Расширенный (E7.2)

• Anti-wash trading (Paxful rule): если обе стороны сделки — рефералы одного партнёра → 50% от стандартной комиссии
• Velocity limit: не больше 5 новых рефералов/день без admin-review
• IP-кластеризация: 3+ регистраций с одного IP/час — флаг
• Анализ «сделок без on-chain подтверждения» — уже работает через reconcile.py, добавим алерт «комиссии за сделки без on-chain»

6.3. Что НЕ делаем

• Device fingerprinting (30–40% false match — research)
• ML/rule-based fraud detection (нет данных на MVP)

7. Compliance (Турция) — критичный раздел

7.1. CMB / MASAK

Текущий статус: у Obmenka нет CASP-лицензии. CMB требует капитал 150M TRY (~$4.1M) для лицензированного обменника. Подача — отдельный проект, не в скоупе.

Ограничения для affiliate-программы: - ❌ Публичная страница «Стать партнёром» на турецком — НЕТ - ❌ Партнёры — резиденты Турции — НЕТ на MVP - ❌ Маркетинг партнёрки в турецких TG-каналах / Instagram TR — НЕТ - ✅ Партнёры — резиденты других стран (RU/EU/global) с не-турецкой аудиторией - ✅ Cashier в Лиман/Лара принимает реф-код от клиента (это не публичная реклама)

После получения CASP-лицензии или ясности с CMB (отдельный этап) — открываем для TR.

7.2. KYC партнёра

MVP: - Имя + контакты (TG/email/phone) - Tax-ID (по стране) - Payout-address TRC20 - Скан паспорта (для физлица) — до первой выплаты

Фаза 2: - Селфи с паспортом - AMLBot screening payout-адреса - Обязательно для всех новых партнёров до accrual

7.3. Withholding tax 1% (TR)

С 1 января 2025 — обязательное удержание для платежей intermediary/e-commerce providers.

Реализация: - Поле affiliates.is_tr_tax_resident BOOLEAN (заполняется при KYC) - При выплате — удерживаем 1% если TR-резидент - В UI открыто показываем: «Удержано 1% по TR-закону» - Месячный отчёт для бухгалтерии (CSV: партнёр, сумма выплат, удержанный tax)

7.4. Список запрещённых юрисдикций

• Партнёры — не из стран в OFAC SDN list, FATF black/grey list
• Рефералы (клиенты) — KYC скан по той же логике (уже есть в нашей системе для крипто-операций > $425)
• RU/BY партнёры — не блокируем (значительная часть нашей клиентской базы), но мониторим санкции относительно конкретных лиц

7.5. Партнёрский договор

Документ PDF/Doc (вне CRM). Подписывается до первой выплаты. Обязательные пункты: 1. Commission structure (модель, %, attribution) 2. Cookie duration (30 дней до 1-й сделки, 24 мес после) 3. Payment terms (USDT-TRC20, min 50, hold 7 дней, network fee + TR withholding с партнёра) 4. Запрещённые активности (cookie stuffing, brand bidding, спам, self-referral) 5. KYC/AML compliance аффилиата 6. Tax responsibility (партнёр сам декларирует кроме того что мы удержали) 7. Termination conditions 8. Confidentiality — нельзя разглашать данные клиентов, использовать иначе чем для привлечения 9. FTC disclosure (для US-аудитории): #ad/#sponsored обязательно 10. Jurisdiction (Турция), dispute resolution

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

Детали в docs/affiliate-research/03-architecture-plan.md. Здесь — сводка изменений относительно v1.

Новые таблицы (6)

1. affiliate_programs — настройки (ставки, hold, min_payout, attribution_days, payout_fee_borne_by)
2. affiliates — партнёры с FK на users (+ is_tr_tax_resident, kyc_status)
3. ref_codes — реф-коды (несколько на партнёра)
4. client_affiliations — история привязок (partial UNIQUE)
5. commission_entries — начисления (UNIQUE deal_id+affiliate_id+tier)
6. payout_requests — запросы выплат + связь с Operation

Изменения существующих

• 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
• operations += source='payout' как новое значение enum

9. UI / Экраны

9.1. Партнёрский кабинет (/aff/*, layout aff_base.html)

Отдельный layout (визуально отличается от админки), но под основным доменом (не на subdomain — экономит инфру).

Privacy: партнёр НЕ видит ФИО/телефон/email/TG-username клиента.

9.2. Админская часть

Новая группа в сайдбаре base.html:

Партнёры
├── /affiliates           — Список
├── /affiliate-programs   — Программы и ставки
└── /payouts              — Ожидающие выплаты

Изменения существующих экранов: - /clients/{id} — блок «Партнёр» (manager может менять, history) - /clients — колонка «Партнёр» + фильтр - /deals/{id} — read-only список комиссий - / (дашборд admin/manager) — виджет «Партнёрская программа»

9.3. Маркетинговые материалы — НЕ предоставляем на MVP

Партнёр сам делает свои креативы. Кабинет даёт только: - Реф-ссылку - QR-код (auto-gen) - Текст «pitch» в README на 3 языках для самостоятельного использования

10. RBAC

2FA: опционально на MVP. Обязательно в фазе 2 для: - Изменения payout-адреса (re-auth) - Запроса выплаты > 500 USDT

11. Фазы реализации

E7.1 MVP (3–4 недели) — что в скоупе

Бэкенд: - Миграции: 6 новых таблиц + ALTER 4 существующих - 1 программа default (0.3% volume, hold 7, min 50, attribution 24 мес) - accrual в routes/deals.py через post-commit hook (eventual consistency) - Hold-cron daily в 04:00 UTC (commission_release.py) - TRC20 fee + TR withholding в логике payout

UI: - Партнёрский кабинет (без 2FA): dashboard, links, clients, earnings, payouts, settings - Админка: /affiliates (CRUD), /affiliate-programs (одна default), /payouts (approve) - Tracking endpoint /r/{code} - Manual attach в карточке клиента и форме сделки - Виджет на дашборде admin

Compliance: - KYC партнёра (паспорт скан до первой выплаты) - is_tr_tax_resident поле + расчёт withholding - Партнёрский договор (PDF, вне CRM) - Запуск только с не-TR партнёрами

Готово когда: 1. Партнёр зарегистрирован (admin), получил ref-код и QR 2. Привёл клиента (через ссылку ИЛИ менеджер ввёл код) 3. Клиент совершил сделку → партнёр видит «+15 USDT pending» в кабинете 4. Через 7 дней → available 5. Партнёр запросил → admin одобрил → партнёр получил USDT-TRC20

E7.2 Расширение (2–3 недели)

• Multi-level: parent_affiliate_id, tier2_pct, denormalized parents (защита от циклов)
• Tier-бонусы (Bronze/Silver/Gold) + monthly recalc cron
• Override-ставки per affiliate
• Anti-wash-trading правило Paxful
• Velocity limits
• 2FA TOTP для роли affiliate
• Automatic payout при threshold (опт)
• UI: дерево даунлайна
• Tax-report экспорт для бухгалтерии

E7.3 Отложено

• Smart-contract automated payouts (своя hot wallet с приватником)
• Self-signup партнёра (с модерацией)
• TG-бот канал привязки (вместе с M5 ТЗ партнёра)
• Webhooks/email-уведомления партнёрам
• A/B-тесты программ
• Отдельный subdomain partners.obmenka...
• Multi-currency payouts (TRY/USD кэш в офисе)
• ML fraud detection

12. Финансовая модель (3 сценария на 6 месяцев)

Допущения

• Средний profit на сделке: $30 USDT (в Анталье)
• Default ставка: 0.3% volume ≈ 30% от profit
• Hold cap 50% от profit

Сценарий A — консервативный

• 5 активных партнёров
• Каждый приводит 5 клиентов
• Клиент делает 3 сделки за 6 мес
• 75 сделок × $30 profit = $2 250 валовая прибыль
• Комиссии партнёрам: ~$675 (30%)
• Чистый дополнительный профит нам: $1 575

Сценарий B — целевой

• 15 активных партнёров (включая 3 «средних»)
• 8 клиентов на партнёра в среднем
• 4 сделки/клиент за 6 мес
• 480 сделок × $40 profit = $19 200
• Комиссии: ~$5 760
• Чистая прибыль: +$13 440

Сценарий C — стресс (партнёры приводят тех же клиентов что и так бы пришли)

• 5 партнёров, привели 50 «дублирующих» клиентов
• Привлекли = $1 500 profit
• Комиссии = $450
• ROI ≈ 0 — но мы получили долгосрочный канал распространения

Решение: запускать MVP с фокусом на сценарий A→B, мониторить cannibalization (опрашивать новых клиентов «откуда пришли» в первые 3 месяца).

13. Технические интеграции

Принцип: минимально-инвазивно, не переписываем сделочный flow.

14. Финальные дефолтные ответы (вместо open questions v1)

Дополнительно зафиксировано: - TRC20 fee — удерживаем с партнёра - Маркетинговые материалы — не предоставляем (партнёр сам) - Refund при paid → списываем с available, если нет → терпим убыток - KPI: 5–8% / 10–15% / 20–25% на 3/6/12 мес - CMB compliance — блокирует TR-партнёров до получения статуса

15. Что НЕ делаем явно и почему

16. Чеклист готовности к запуску E7.1

• [ ] Партнёрский договор готов (PDF, юр.провер.)
• [ ] Подобрано 3–5 пилотных партнёров (не-TR резиденты)
• [ ] Их payout-адреса проверены через AMLBot
• [ ] Мини-страница landing.html (опционально для пилота)
• [ ] Тест-сценарии (E2E) написаны
• [ ] Backup БД до миграции
• [ ] Bbf-роллбек миграции протестирован
• [ ] Hot wallet с USDT-TRC20 для тестовых payouts
• [ ] Admin прошёл walkthrough кабинета
• [ ] Партнёрам выдан "Getting Started" guide на 3 языках

17. Открытые вопросы к пользователю (минимум, требуют решения)

Все технические/operational ответы зафиксированы выше. Остаются 3 бизнес-вопроса:

1. CMB-блок: согласен ли ты с тем, что MVP запускаем БЕЗ турецких партнёров? Или нужна юридическая консультация по конкретному кейсу до этого?

2. Пилотные партнёры: есть ли у тебя уже на примете 3–5 кандидатов в партнёры? Или начинаем с поиска?

3. Стартовая программа: запускаем с одной default (0.3% volume), или сразу заводим vip-profit-share для каких-то знакомых каналов которые требуют больше?

Приложение: Изменения относительно v1

Применено все 19 правок из критики.