PRD v1: Affiliate-программа для Obmenka

Версия: 1.0 (черновик для критики) Дата: 2026-05-16 Автор: AI assistant (синтез из 3 источников — см. docs/affiliate-research/) Статус: на внутренней критике, до v2

1. Executive Summary

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

Базовая модель (E7.1 MVP): - 1 уровень партнёров (без sub-affiliate в MVP) - Комиссия: 30% от нашей маржи (profit_usdt) на каждой сделке приведённого клиента - Lifetime-привязка после первой сделки - Cookie window 30 дней до первой сделки - Минимум выплаты 50 USDT, hold 7 дней, USDT-TRC20 - Регистрация через admin (нет self-signup)

Бизнес-цель: дешевый канал привлечения новых клиентов с предсказуемой unit-экономикой. Платим только за результат (профит-shared), а не за лиды.

Ожидаемые метрики через 6 месяцев: - 15–30 активных партнёров - ≥20% новых клиентов приведены партнёрами - LTV/CAC через партнёров > 5× (т.к. CAC = % от их же сделок)

Объём работы: - E7.1 MVP: 3–4 недели - E7.2 (multi-level + 2FA + автоплатежи): 2–3 недели

2. Бизнес-обоснование

2.1. Почему запускаем сейчас

После E1–E6 у нас есть рабочая CRM с реальными сделками и блокчейн-сверкой. Появилась стабильная база, на которую можно «накручивать» канал привлечения. Без партнёрки CAC через рекламу в Анталье в туристический сезон = $30–100/клиент. Партнёрка платит только когда клиент уже принёс деньги.

2.2. Почему именно крипто-обменник нуждается в affiliate

Из research: - Binance/Bybit/OKX/MEXC — все делают по 30–50% от торговой комиссии, это стандарт индустрии 2025–2026. - Bestchange (агрегатор) — 30% Level 1 + 10% Level 2 + lifetime. - Coinsfera (прямой конкурент в Стамбуле) имеет partner-программу, детали закрыты.

Без affiliate — мы единственные в Анталье без партнёрки. Это упускаемый рост.

2.3. Метрики успеха модуля (через 3 / 6 месяцев)

3. Целевая аудитория партнёров и сценарии использования

3.1. Сегменты партнёров

3.2. Ключевые user stories

Партнёр-блогер: 1. Регистрируется через admin (на MVP), получает ref-код и QR. 2. Постит сторис «Меняю крипту у [ссылка/QR]». 3. Клиент переходит, обращается в Telegram/приходит в офис. 4. Менеджер/кассир видит «есть привязка к партнёру по cookie/коду», оформляет сделку. 5. Партнёр в кабинете видит — «+15 USDT начислено, доступно через 7 дней». 6. Запрашивает выплату при 50+ USDT → получает USDT-TRC20 в течение 48 часов.

Кассир в Лиман-точке: 1. Турист говорит «у меня код от Анны: ANNA-IST». 2. Кассир в CRM открывает форму новой сделки. 3. В поле «Партнёр» — autocomplete по коду или имени партнёра. 4. Создаёт сделку как обычно → система сама начислит комиссию.

Admin: 1. Получает заявку от потенциального партнёра в TG. 2. Создаёт Affiliate в /affiliates/new (имя, контакты, payout-адрес). 3. Подписывает партнёрский договор (вне CRM, в PDF). 4. Раз в неделю проверяет /payouts на ожидающие запросы. 5. Одобряет, выбирает Operation с фактической on-chain транзакцией выплаты.

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

4.1. Базовая формула (E7.1)

commission_amount_usdt = (deal.profit_usdt × tier1_pct) − fixed_overhead

где: - deal.profit_usdt — уже считаемая прибыль = (indicative_rate − applied_rate) × give_amount × FX_to_USDT[get_asset] - tier1_pct = 30% для default-программы

Почему от profit_usdt, а не от volume:

Решение для MVP: profit-based с возможностью переключения программы на volume-based для отдельных партнёров (отдельная программа).

4.2. Примеры расчёта

4.3. Multi-level (E7.2)

• Tier 1 (прямой партнёр клиента) = 30% от profit
• Tier 2 (партнёр, который привёл Tier 1) = 5% от profit (НЕ от Tier 1)
• Tier 3 = не реализуем даже в фазе 2

Защита от каскадной мотивации к sub-affiliate fraud: tier2 существенно ниже tier1 (5% vs 30%), чтобы партнёру было невыгодно создавать «фейкового sub-партнёра» ради 5% (учитывая, что эти sub-партнёры должны пройти admin-approval и KYC).

4.4. Tier'ы по объёму (E7.2)

Опционально, если оправдает себя: - Bronze (default): 30% Tier1 / 5% Tier2 - Silver (≥ $500 заработанной партнёром маржи за 30 дней): 35% / 5% - Gold (≥ $2000): 40% / 7%

Переоценка ежемесячно, protection period 2 месяца при downgrade (Binance-стиль).

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

• Сделки в UAH/RUB (опционально, по решению admin) — комиссия 50% от стандартной (т.к. эти валюты у нас прокси-каналы, маржа меньше)
• Сделки внутрениие переводы (op_type=internal) — комиссия 0
• Cancelled сделки — 0
• Cделки в excluded_assets программы — 0
• Cap на одну сделку — 200 USDT (защита от «one shot fraud»)

5. Tracking и Attribution

5.1. Способы привязки клиента к партнёру

3 канала:

1. Реферальная ссылка https://obmenka.felix.nohumaninside.me/r/{code} - Публичный endpoint без auth - Инкрементит ref_codes.clicks_count - Ставит cookie obm_ref (signed, TTL 30 дней) - 302-redirect на main landing - При создании нового Client → cookie → client.referrer_affiliate_id

2. Manual ввод менеджером/кассиром - В форме новой сделки или карточке клиента — поле «Партнёр» с autocomplete - Кассир выбирает по ref-коду (клиент сказал устно) или имени партнёра - Запись в client_affiliations с source='manual', reason обязателен

3. Self-claim через TG-бот (фаза 3) - Клиент пишет боту «у меня код TGTR2026» - Бот резолвит и привязывает

5.2. Attribution window

• До первой сделки: cookie 30 дней (стандарт e-commerce)
• После первой сделки клиента: lifetime-привязка (как Bybit/Binance)
• Lifetime означает: все будущие сделки клиента → партнёру, пока админ не перепривяжет вручную

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

• Менеджер может переключить клиента на другого партнёра (требует reason)
• Старая запись в client_affiliations помечается detached_at
• Уже начисленные комиссии не меняются (snapshot в commission_entries.affiliate_id)
• Новые сделки идут новому партнёру

5.4. Anti-conflict правило

Если cookie cтавит partner A, а менеджер хочет привязать к partner B (например, клиент пришёл по знакомству) — это требует подтверждения admin или явного указания «cookie перекрыта» в форме с причиной.

6. Anti-fraud

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

6.2. Anti-wash-trading (E7.2)

Правило Paxful: если у одной сделки обе стороны — рефералы одного партнёра, комиссия снижается до 50% от стандартной. Например, 30% → 15%.

Реализация: при accrue смотрим, есть ли в другой стороне сделки клиент с тем же referrer_affiliate_id. Сложно для крипто-on-chain стороны (там анонимный wallet), но для cash↔crypto в обменнике — обе стороны имеют клиента.

6.3. Velocity limits (E7.2)

• Не больше 5 новых рефералов в день от одного партнёра без admin review
• Не больше 50 в месяц без upgrade tier

6.4. Что НЕ делаем в MVP

• Device fingerprinting (30–40% false match per research)
• ML/rule-based fraud detection (нет данных для обучения)
• IP-кластеризация (можно проще через self-referral check)

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

7.1. Состояния commission_entry

[создан в момент Deal → done]
       ↓
   pending
       ↓ (hold_days=7 истекли AND сделка не cancelled)
   available
       ↓ (партнёр запросил payout, admin одобрил)
   paid
       ↓ (опционально, через reconcile)
   linked to raw_blockchain_tx

Альтернативные пути: - voided — при failure-проверке (self-referral, too_small, asset excluded) - reversed — при отмене сделки уже после paid (баланс может уйти в минус, ручной разбор)

7.2. Hold период

7 дней для MVP. Обоснование: - Стандарт индустрии для крипто без card-chargebacks = 7–14 дней - Достаточно для AML-проверки реферальной сделки - Не слишком долго для UX партнёра

Программа может настраивать это поле (по умолчанию 7).

7.3. Выплаты

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

Условие: balance_available ≥ 50 USDT (минимум программы).

Approval flow: 1. Partner → POST /aff/payouts/request (если ≥ min) → создаётся payout_request(status=pending) 2. Admin видит в /payouts, в pending 3. Admin делает USDT-TRC20 перевод (вручную из cold wallet или через систему) 4. Admin в админке нажимает «Одобрить» → вводит/выбирает Operation(op_type=crypto_out) (та самая Operation выплаты) 5. Все commission_entries.available партнёра до суммы запроса → paid 6. reconcile.py автоматически свяжет payout_request.matched_raw_tx_id с реальной on-chain транзакцией

Periodicity: на MVP — по запросу. В E7.2 — опция «каждую среду авто» / «при threshold».

7.4. Запрос-вывод vs автомат

8. Модель данных (краткая сводка)

Детали в docs/affiliate-research/03-architecture-plan.md.

Новые таблицы: - affiliate_programs — настройки программы (ставки, hold, min_payout, attribution) - affiliates — партнёры (с FK на users для auth) - ref_codes — реф-коды (несколько на партнёра) - client_affiliations — история привязок (partial UNIQUE на одну активную) - commission_entries — начисления (UNIQUE (deal_id, affiliate_id, tier)) - 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

Размер: - На 150 сделок/мес × 1 партнёр в среднем = 150 commission_entries/мес = ~1800/год - При 30 партнёрах и 10k сделок/мес (далёкая перспектива) — 30k/мес = 360k/год. Тоже нормально для Postgres.

9. UX / Экраны

9.1. Партнёрский кабинет — отдельный layout aff_base.html

Зачем отдельный: визуально отличается от админки (другой цвет/брендинг), партнёр и админ не путаются. Под URL'ом /aff/*, не на отдельном subdomain в MVP (потому что Caddy config + cert hassle).

Экраны:

9.2. Админская часть — под существующим сайдбаром

Добавляется новая группа в base.html:

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

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

9.3. Привязка клиента к партнёру (для кассира)

В форме новой сделки /deals/new добавляется опциональное поле «Реф-код / Партнёр» — autocomplete по активным ref_codes.code + affiliates.display_name. Если поле заполнено и client.referrer_affiliate_id IS NULL — привязываем клиента к этому партнёру (с source='manual').

10. RBAC и privacy

10.1. Новая роль affiliate

Может: - Видеть свой кабинет (все /aff/* пути) - Видеть свою статистику (агрегаты) - Запрашивать выплату - Менять payout-адрес и пароль

НЕ может: - Видеть других партнёров - Видеть детали клиентов (только псевдоним C-XXXX + агрегаты) - Видеть детали сделок (только дата + тип + сумма комиссии) - Видеть, кто его upline (parent_affiliate_id скрыт) - Создавать сделки или изменять клиентов

10.2. Обновлённая NAV_BY_ROLE

"admin":      {..., "affiliates", "affiliate_programs", "payouts"},
"manager":    {..., "affiliates"},  # видит список, может привязывать клиентов
"accountant": {..., "affiliates", "payouts"},  # read-only для отчётов
"cashier":    {...},  # без affiliate в сайдбаре, только в форме сделки
"viewer":     {...},  # без изменений
"affiliate":  {"aff_dashboard", "aff_links", "aff_clients", "aff_earnings", "aff_payouts", "aff_settings"},

10.3. Privacy

Партнёр в кабинете видит: - ✅ Псевдоним клиента C-XXXX - ✅ Дата привязки - ✅ Количество и совокупный объём сделок клиента - ❌ ФИО / телефон / email / Telegram-username клиента - ❌ Детали отдельных сделок (валюты, контрагенты)

Это критично для: - Защиты от утечки клиентской базы (если у партнёра скомпрометирован пароль) - GDPR-минимизации - Защиты от перехвата клиентов конкурентами (если партнёр станет нелояльным)

10.4. 2FA

На MVP: опционально. Партнёр включает в /aff/settings. По умолчанию выключено.

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

11. Юридический контекст (Турция)

Из research: - MASAK 2024: KYC обязателен для каждой crypto-операции > 15 000 TRY (~$425). У нас это всё равно есть для клиентов. - С 1 января 2025: 1% withholding tax на платежи intermediary/e-commerce service providers. Затрагивает выплаты партнёрам. - CMB регулирует криптообменники как CASPs. Минимальный капитал 150M TRY (~$4.1M) для получения лицензии. На MVP не требуется (мы не подаём заявку), но через 6–12 месяцев — нужно обсудить. - Без лицензии CASP — уголовка 3–5 лет. Делаем минимум видимости в Турции, реклама партнёров на турецком — только с расчётом на это.

11.1. Партнёрский договор (обязательно перед первой выплатой)

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

11.2. KYC партнёра

Минимум: - Имя, контакты (TG + email + phone) - Tax-ID (TR — TC Kimlik для резидентов, foreign tax-ID для нерезидентов) - Payout-кошелёк (TRC20 address) + screening через AMLBot/Chainalysis - Страна резидентства

Требуется до: - Первой выплаты > 50 USDT (опционально на MVP) - Любого payout в фазе 2 (обязательно) - Для физических партнёров с monthly payout > €1000 — расширенный KYC (паспорт + селфи)

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

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

Цель: запустить программу с 3–5 ручными партнёрами, плоская комиссия от profit, ручные выплаты.

В scope: - Миграции: 6 новых таблиц + ALTER 4 существующих - 1 программа default (profit_usdt × 30%, hold 7 дней, min 50 USDT) - БЕЗ multi-level (max_tier_depth=1) - attribution = lifetime после первой сделки + cookie 30 дней до - Партнёрский кабинет (без 2FA) - Tracking /r/{code} + cookie + auto-attach при создании клиента - Manual attach менеджером в карточке клиента или в форме сделки - Accrual в момент deal.status → done (модификация routes/deals.py) - Hold-cron job каждый час - Admin: CRUD affiliates, программа (одна default), approve payouts - Audit пишется через существующий record_audit()

Не в scope: - Multi-level (tier2_parent_id) - Automatic payouts по threshold - 2FA TOTP - Self-signup партнёра - Fraud detection кроме базовых проверок - Отдельный subdomain - Webhooks/нотификации

Готово когда: партнёр может зарегистрироваться (через admin), получить ref-код, привести клиента, увидеть свою комиссию в кабинете, запросить выплату, admin её одобрить.

E7.2 — Multi-level + автоматизация (2–3 недели)

В scope: - parent_affiliate_id + tier2_parent_id + tier3_parent_id (denorm) - affiliate_programs.tier2_pct (5% от profit), max_tier_depth ≤ 2 - Override per affiliate (override_tier1/2_pct) - attribution_mode = first_n_days, first_deal_only опции - 2FA TOTP для роли affiliate - Anti-self-referral check (tg_username/phone match) - Anti-wash-trading правило Paxful - Velocity limits (5 рефералов/день) - Automatic payout creation при threshold ≥ 200 USDT - Scheduled payouts (weekly/monthly opt-in) - UI: дерево даунлайна в карточке партнёра - Tier-bonus (Bronze/Silver/Gold)

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

• Smart-contract выплаты (USDT-TRC20 авто, с приватным ключом)
• Self-signup партнёра (с модерацией)
• ML/rule fraud detection
• Отдельный subdomain partners.obmenka.felix...
• Webhooks для партнёров (когда у их клиента сделка)
• Email-уведомления партнёрам (digest)
• A/B-тесты программ (когорта получает другую ставку)
• Tax reporting export (для бухгалтерии)
• Multi-currency payouts (TRY/USD cash в офисе)

13. Открытые вопросы для согласования

13.1. Бизнес-вопросы (требуют ответа от пользователя/руководителя)

1. Базовая ставка 30% от profit_usdt — приемлемо? Это даёт партнёру 30% от нашей прибыли. На сделке с 100 USDT профита → 30 USDT партнёру. Если хочется 20% или 40% — скажи.

2. Cap 200 USDT на одну сделку — нужен для защиты от «один раз привёл VIP-клиента с миллионной сделкой и получил пожизненную полу-прибыль». Альтернатива: убрать cap (доверять рынку). Что выбираем?

3. Lifetime-привязка после первой сделки — стандарт индустрии (Binance/Bybit), но это значит платить вечно. Альтернатива: limited window (например, 12 месяцев с момента первой сделки). Через 12 мес клиент «отвязывается».

4. Tier 2 (sub-affiliate) в фазе 2 — оставляем 5%, или предпочитаешь не делать multi-level вообще?

5. Минимум payout 50 USDT — низковато для нашего рынка (50$ это нормально для турецкого бизнес-сегмента), или поднять до 100?

6. Withholding tax 1% — мы удерживаем при выплате (как Турция требует с 2025) или платим сами и закладываем в комиссию?

7. Список запрещённых стран для рефералов — будут ли санкционные ограничения? RU/BY/Иран — пускаем партнёров оттуда или нет?

13.2. Open для архитектуры (могу решить сам, но хочу подтверждения)

8. base_model per program: оставляем profit_usdt как основу или добавляем volume_usdt как опцию для отдельных программ? Я бы сделал обе доступны, но default = profit_usdt.

9. 2FA для партнёра — опционально на MVP, обязательно в фазе 2. Согласен?

10. Партнёрский кабинет под /aff/* или на отдельном subdomain? Я бы оставил под основным — Caddy уже настроен, экономит 1 день инфры.

14. Что НЕ делаем в первой версии и почему

15. Связь с существующей системой

Модуль интегрируется минимально-инвазивно:

Принцип: не переписывать сделочный flow, а добавить «модуль рядом» с явными точками вызова.

16. Приложение: сравнительная таблица моделей (для обоснования)

Конец PRD v1. Следующий шаг — критика и переработка в v2.