Loading documentation...
Preparing Ring content
Концепції, цінність і типові сценарії
Концепції, цінність і типові сценарії
Preparing Ring content
Preparing Ring content
Preparing Ring content
Ring Platform поєднує застарілу інфраструктуру комісій продавців із модулем зростання refcodes. Один cookie атрибуції керує двома рейками виплат: продавці фінансують фіатну реферальну комісію через ERP-розрахунки, а платформа фінансує токенові винагороди реферерів через ончейн-мінтер. Обидві рейки використовують orderReference для перехресного аудиту.
Реферери отримують токени. Продавці фінансують свою частку реферальної комісії з розрахунку. Покупці бачать реферальний бейдж під час checkout, якщо їх атрибутовано. Оператори схвалюють фіатні мінти, запускають cron для черги та переглядають комісії за адресою /admin/store/commissions.
Докладніше: Реферальні коди (refcodes) · Архітектура refcodes · Комісії ERP
| Рейка | Хто платить | Механізм | Коли запускається |
|---|---|---|---|
| ERP (фінансує продавець) | Чиста виплата продавцю | calculateCommission() → settlements.metadata.commissionBreakdown.referralCommission | Оплачений order магазину (WayForPay або кредит) |
| Refcodes (фінансує платформа) | Скарбниця / мінтер платформи | ReferralRewardService → ReferralRewards.payReferral у Polygon | Після оплати order (фіат: після схвалення; кредит: одразу) |
Обидві рейки використовують resolveReferralCommissionPercent (features/store/lib/referral-commission.ts) — override продукту → конфігурація продавця → типовий параметр платформи (5%) → env REFERRAL_REWARD_PERCENT.
У межах: замовлення магазину та оновлення membership. Поза межами цієї ітерації: реферали просування новин і знижки referee під час checkout (стимул лише для реферера).
Перехід із ?ref= — proxy.ts встановлює httpOnly ring_ref і доступний клієнту ring_ref_visible (30 днів, перший дотик).
Beacon візиту — ReferralAttributionEffect викликає POST /api/refcodes/track; visitDaily групує статистику dashboard (утримання 28 днів).
Збереження signup — signIn Auth.js для нових користувачів запускає persistSignupReferralAttribution, тому users.data.referredBy переживає завершення cookie.
Checkout — крок Review показує ReferralCheckoutBadge; API order повертають referralApplied + referralCode; кредитний checkout показує toast, WayForPay зберігає flash у sessionStorage.
Успішна оплата — webhook магазину або кредитний шлях записує settlements (ERP) і referral_rewards (токени). Webhook membership викликає ReferralRewardService.onMembershipPaid, якщо задано referredBy.
/refcodes — посилання, історія винагород, статистика візитів (усього / сьогодні / 7d / 28d).
/admin/refcodes — схвалення фіатних винагород, пакетний мінт, агрегати візитів.
/admin/store/commissions — ledger розрахунків, реферальна розбивка, виплати.
Мапа інтеграції cookie → ledger → contract та ключі ідемпотентності.
Кожна атрибутована оплачена подія повинна мати те саме orderReference (рядок PaymentConductor) у таких записах:
| Запис | Поле |
|---|---|
settlements | orderId / metadata |
erp_sales_assists | orderId |
referral_rewards | orderReference (унікальний індекс) |
| On-chain | keccak256(orderReference) у ReferralRewards.paidOrders |
Smoke: scripts/smoke-erp-referral-pipeline.cts, scripts/smoke-growth-pipelines.cts, scripts/smoke-refcodes-http.cts (потрібні DB_BACKEND_MODE + NODE_OPTIONS=--conditions=react-server).
| Крок | Дія |
|---|---|
| 1. Міграції | Застосуйте 005_refcodes_schema.sql, потім 007_settlements_schema.sql. |
| 2. Env | Заповніть REFERRAL CODES і CRON_SECRET у env.local.template; розгорніть проксі ReferralRewards і надайте йому право мінту. |
| 3. Cron | Заплануйте GET /api/cron/refcodes-mint з Authorization: Bearer $CRON_SECRET (до 20 схвалених винагород за запуск). |
| 4. Перевірка | Referred order → settlements + erp_sales_assists + referral_rewards зі спільним orderReference. |
Запустіть ./scripts/run-all-smokes.sh (встановлює DB_BACKEND_MODE і NODE_OPTIONS=--conditions=react-server). Цільові набори: smoke-erp-referral-pipeline.cts, smoke-growth-pipelines.cts, smoke-refcodes-http.cts.
Поглиблення: UI користувача/адміністратора, деплой contract і env для токенових винагород.
Той самий процес: ієрархія розрахунків, фінансованих продавцем, і режими виплат.
Залежність: оплачений commitSaleForOrder працює поруч із settlement для замовлень магазину.
Передумова: webhooks і контракт orderReference.
Ring Platform поєднує застарілу інфраструктуру комісій продавців із модулем зростання refcodes. Один cookie атрибуції керує двома рейками виплат: продавці фінансують фіатну реферальну комісію через ERP-розрахунки, а платформа фінансує токенові винагороди реферерів через ончейн-мінтер. Обидві рейки використовують orderReference для перехресного аудиту.
Реферери отримують токени. Продавці фінансують свою частку реферальної комісії з розрахунку. Покупці бачать реферальний бейдж під час checkout, якщо їх атрибутовано. Оператори схвалюють фіатні мінти, запускають cron для черги та переглядають комісії за адресою /admin/store/commissions.
Докладніше: Реферальні коди (refcodes) · Архітектура refcodes · Комісії ERP
| Рейка | Хто платить | Механізм | Коли запускається |
|---|---|---|---|
| ERP (фінансує продавець) | Чиста виплата продавцю | calculateCommission() → settlements.metadata.commissionBreakdown.referralCommission | Оплачений order магазину (WayForPay або кредит) |
| Refcodes (фінансує платформа) | Скарбниця / мінтер платформи | ReferralRewardService → ReferralRewards.payReferral у Polygon | Після оплати order (фіат: після схвалення; кредит: одразу) |
Обидві рейки використовують resolveReferralCommissionPercent (features/store/lib/referral-commission.ts) — override продукту → конфігурація продавця → типовий параметр платформи (5%) → env REFERRAL_REWARD_PERCENT.
У межах: замовлення магазину та оновлення membership. Поза межами цієї ітерації: реферали просування новин і знижки referee під час checkout (стимул лише для реферера).
Перехід із ?ref= — proxy.ts встановлює httpOnly ring_ref і доступний клієнту ring_ref_visible (30 днів, перший дотик).
Beacon візиту — ReferralAttributionEffect викликає POST /api/refcodes/track; visitDaily групує статистику dashboard (утримання 28 днів).
Збереження signup — signIn Auth.js для нових користувачів запускає persistSignupReferralAttribution, тому users.data.referredBy переживає завершення cookie.
Checkout — крок Review показує ReferralCheckoutBadge; API order повертають referralApplied + referralCode; кредитний checkout показує toast, WayForPay зберігає flash у sessionStorage.
Успішна оплата — webhook магазину або кредитний шлях записує settlements (ERP) і referral_rewards (токени). Webhook membership викликає ReferralRewardService.onMembershipPaid, якщо задано referredBy.
/refcodes — посилання, історія винагород, статистика візитів (усього / сьогодні / 7d / 28d).
/admin/refcodes — схвалення фіатних винагород, пакетний мінт, агрегати візитів.
/admin/store/commissions — ledger розрахунків, реферальна розбивка, виплати.
Мапа інтеграції cookie → ledger → contract та ключі ідемпотентності.
Кожна атрибутована оплачена подія повинна мати те саме orderReference (рядок PaymentConductor) у таких записах:
| Запис | Поле |
|---|---|
settlements | orderId / metadata |
erp_sales_assists | orderId |
referral_rewards | orderReference (унікальний індекс) |
| On-chain | keccak256(orderReference) у ReferralRewards.paidOrders |
Smoke: scripts/smoke-erp-referral-pipeline.cts, scripts/smoke-growth-pipelines.cts, scripts/smoke-refcodes-http.cts (потрібні DB_BACKEND_MODE + NODE_OPTIONS=--conditions=react-server).
| Крок | Дія |
|---|---|
| 1. Міграції | Застосуйте 005_refcodes_schema.sql, потім 007_settlements_schema.sql. |
| 2. Env | Заповніть REFERRAL CODES і CRON_SECRET у env.local.template; розгорніть проксі ReferralRewards і надайте йому право мінту. |
| 3. Cron | Заплануйте GET /api/cron/refcodes-mint з Authorization: Bearer $CRON_SECRET (до 20 схвалених винагород за запуск). |
| 4. Перевірка | Referred order → settlements + erp_sales_assists + referral_rewards зі спільним orderReference. |
Запустіть ./scripts/run-all-smokes.sh (встановлює DB_BACKEND_MODE і NODE_OPTIONS=--conditions=react-server). Цільові набори: smoke-erp-referral-pipeline.cts, smoke-growth-pipelines.cts, smoke-refcodes-http.cts.
Поглиблення: UI користувача/адміністратора, деплой contract і env для токенових винагород.
Той самий процес: ієрархія розрахунків, фінансованих продавцем, і режими виплат.
Залежність: оплачений commitSaleForOrder працює поруч із settlement для замовлень магазину.
Передумова: webhooks і контракт orderReference.
Ring Platform поєднує застарілу інфраструктуру комісій продавців із модулем зростання refcodes. Один cookie атрибуції керує двома рейками виплат: продавці фінансують фіатну реферальну комісію через ERP-розрахунки, а платформа фінансує токенові винагороди реферерів через ончейн-мінтер. Обидві рейки використовують orderReference для перехресного аудиту.
Реферери отримують токени. Продавці фінансують свою частку реферальної комісії з розрахунку. Покупці бачать реферальний бейдж під час checkout, якщо їх атрибутовано. Оператори схвалюють фіатні мінти, запускають cron для черги та переглядають комісії за адресою /admin/store/commissions.
Докладніше: Реферальні коди (refcodes) · Архітектура refcodes · Комісії ERP
| Рейка | Хто платить | Механізм | Коли запускається |
|---|---|---|---|
| ERP (фінансує продавець) | Чиста виплата продавцю | calculateCommission() → settlements.metadata.commissionBreakdown.referralCommission | Оплачений order магазину (WayForPay або кредит) |
| Refcodes (фінансує платформа) | Скарбниця / мінтер платформи | ReferralRewardService → ReferralRewards.payReferral у Polygon | Після оплати order (фіат: після схвалення; кредит: одразу) |
Обидві рейки використовують resolveReferralCommissionPercent (features/store/lib/referral-commission.ts) — override продукту → конфігурація продавця → типовий параметр платформи (5%) → env REFERRAL_REWARD_PERCENT.
У межах: замовлення магазину та оновлення membership. Поза межами цієї ітерації: реферали просування новин і знижки referee під час checkout (стимул лише для реферера).
Перехід із ?ref= — proxy.ts встановлює httpOnly ring_ref і доступний клієнту ring_ref_visible (30 днів, перший дотик).
Beacon візиту — ReferralAttributionEffect викликає POST /api/refcodes/track; visitDaily групує статистику dashboard (утримання 28 днів).
Збереження signup — signIn Auth.js для нових користувачів запускає persistSignupReferralAttribution, тому users.data.referredBy переживає завершення cookie.
Checkout — крок Review показує ReferralCheckoutBadge; API order повертають referralApplied + referralCode; кредитний checkout показує toast, WayForPay зберігає flash у sessionStorage.
Успішна оплата — webhook магазину або кредитний шлях записує settlements (ERP) і referral_rewards (токени). Webhook membership викликає ReferralRewardService.onMembershipPaid, якщо задано referredBy.
/refcodes — посилання, історія винагород, статистика візитів (усього / сьогодні / 7d / 28d).
/admin/refcodes — схвалення фіатних винагород, пакетний мінт, агрегати візитів.
/admin/store/commissions — ledger розрахунків, реферальна розбивка, виплати.
Мапа інтеграції cookie → ledger → contract та ключі ідемпотентності.
Кожна атрибутована оплачена подія повинна мати те саме orderReference (рядок PaymentConductor) у таких записах:
| Запис | Поле |
|---|---|
settlements | orderId / metadata |
erp_sales_assists | orderId |
referral_rewards | orderReference (унікальний індекс) |
| On-chain | keccak256(orderReference) у ReferralRewards.paidOrders |
Smoke: scripts/smoke-erp-referral-pipeline.cts, scripts/smoke-growth-pipelines.cts, scripts/smoke-refcodes-http.cts (потрібні DB_BACKEND_MODE + NODE_OPTIONS=--conditions=react-server).
| Крок | Дія |
|---|---|
| 1. Міграції | Застосуйте 005_refcodes_schema.sql, потім 007_settlements_schema.sql. |
| 2. Env | Заповніть REFERRAL CODES і CRON_SECRET у env.local.template; розгорніть проксі ReferralRewards і надайте йому право мінту. |
| 3. Cron | Заплануйте GET /api/cron/refcodes-mint з Authorization: Bearer $CRON_SECRET (до 20 схвалених винагород за запуск). |
| 4. Перевірка | Referred order → settlements + erp_sales_assists + referral_rewards зі спільним orderReference. |
Запустіть ./scripts/run-all-smokes.sh (встановлює DB_BACKEND_MODE і NODE_OPTIONS=--conditions=react-server). Цільові набори: smoke-erp-referral-pipeline.cts, smoke-growth-pipelines.cts, smoke-refcodes-http.cts.
Поглиблення: UI користувача/адміністратора, деплой contract і env для токенових винагород.
Той самий процес: ієрархія розрахунків, фінансованих продавцем, і режими виплат.
Залежність: оплачений commitSaleForOrder працює поруч із settlement для замовлень магазину.
Передумова: webhooks і контракт orderReference.
Передумова: checkout і потоки продавця живлять referred orders.
Передумова: checkout і потоки продавця живлять referred orders.
Передумова: checkout і потоки продавця живлять referred orders.