Building a Robust Bonus Engine in Go: Mastering Accrual, Wager, and Compliance

Avatar photoByAdil

Building a Robust Bonus Engine in Go: Mastering Accrual, Wager, and Compliance

Бонуси — це хліб з маслом у багатьох онлайн-бізнесах, від ігрових платформ до e-commerce. Вони приваблюють нових клієнтів і утримують існуючих. Але за привабливою оболонкою бонусних пропозицій ховається складна логіка, яка потребує точної і надійної реалізації. Неправильне нарахування або облік бонусів може призвести до фінансових втрат, проблем з регуляторами або незадоволення клієнтів.

У цій статті ми зануримося у світ бонусних двигунів (Bonus Engines), розберемо ключові компоненти їх архітектури та розглянемо, як мова програмування Go може допомогти нам створити ефективне, масштабоване та відмовостійке рішення.

1. Типи бонусів: Різноманіття мотивації

Перед тим як говорити про реалізацію, давайте окреслимо основні типи бонусів, з якими нам доведеться працювати. Кожен тип має свою специфіку і вимагає гнучкої системи обліку.

  • Deposit Bonus (Бонус на депозит): Найпоширеніший тип. Гравець отримує відсоток від свого депозиту як бонусні кошти. Наприклад, “100% бонус до 100$” означає, що при депозиті в 100$ гравець отримує ще 100$ бонусних коштів.
  • Freespins (Безкоштовні обертання): Зазвичай використовується в ігрових автоматах. Гравець отримує певну кількість обертань на конкретному слоті без використання власних коштів. Виграші з фріспінів часто нараховуються як бонусні кошти, що підлягають відіграшу.
  • Cashback (Кешбек): Повернення частини програних коштів або відсотків від загальної суми ставок за певний період. Це може бути прямий кеш (реальні кошти) або бонусний кеш (з вейджер-вимогами).
  • Rakeback (Рейкбек): Поширений у покері та деяких інших карткових іграх. Повернення відсотка від рейку (комісії, що стягується з банку кожної роздачі) гравцеві.

Go-підхід: У Go ми могли б моделювати різні типи бонусів за допомогою інтерфейсів та структур. 

package bonusengine

import "time"

type BonusType string

const (
    DepositBonusType  BonusType = "deposit_bonus"
    FreespinsBonusType BonusType = "freespins"
    CashbackBonusType BonusType = "cashback"
    RakebackBonusType BonusType = "rakeback"
)

type Bonus struct {
    ID         string
    UserID     string
    Type       BonusType
    Amount     float64 // Розмір бонусу
    Currency   string
    IssuedAt   time.Time
    ExpiresAt  time.Time
    Status     BonusStatus
    Wager      WagerDetails // Деталі по відіграшу
    Meta       map[string]interface{} // Для специфічних даних (напр., id гри для фріспінів)
}

type BonusStatus string

const (
    Pending  BonusStatus = "pending"
    Active   BonusStatus = "active"
    Wagering BonusStatus = "wagering"
    Completed BonusStatus = "completed"
    Cancelled BonusStatus = "cancelled"
    Expired  BonusStatus = "expired"
)

2. Wager Requirements Calculation (Розрахунок вимог до відіграшу)

Саме тут починаються справжні складнощі. Wager (вейджер) — це вимога до гравця зробити ставки на певну суму, перш ніж бонусні кошти та виграші від них стануть доступними для виведення.

  • Формула: Загальна сума ставок = Розмір Бонусу * Коефіцієнт Вейджера. Наприклад, бонус 100$ з вейджером x30 означає, що гравець повинен зробити ставки на 3000$ (100 * 30).
  • Прогрес відіграшу: Система повинна постійно відстежувати, скільки гравець вже відіграв і скільки ще залишилося.

2.1. Game Contribution до Wager

Не всі ігри однаково сприяють відіграшу. Це критичний аспект, який захищає оператора від швидкого “відмивання” бонусів.

  • Slots (Ігрові автомати): Зазвичай 100% внеску. Ставка в 1$ повністю йде в залік вейджера.
  • Blackjack, Roulette, Baccarat (Настільні ігри): Зазвичай 10-20% внеску. Ставка в 1$ може зараховуватися як 0.10$ або 0.20$ до вейджера через меншу маржу казино і можливість “безпечних” ставок.
  • Live Casino, Sports Betting: Можуть мати власні, часто менші відсотки або складніші правила внеску.

Go-підхід: Для розрахунку прогресу відіграшу нам потрібна функція, яка враховуватиме тип гри та її внесок. 

package bonusengine

// GameContributionRates визначає відсоток внеску кожної гри до вейджера
var GameContributionRates = map[string]float64{
    "slot_game":    1.0,  // 100%
    "blackjack":    0.1,  // 10%
    "roulette":     0.2,  // 20%
    "baccarat":     0.15, // 15%
    "live_poker":   0.05, // 5%
    "sport_betting": 0.5, // 50%
}

type WagerDetails struct {
    RequiredAmount float64
    CurrentProgress float64
    WagerMultiplier float64
}

// CalculateWagerProgress оновлює прогрес відіграшу бонусу
func (b *Bonus) CalculateWagerProgress(betAmount float64, gameType string) {
    if b.Status != Wagering {
        return // Бонус не знаходиться в стані відіграшу
    }

    contributionRate, exists := GameContributionRates[gameType]
    if !exists {
        contributionRate = 0.0 // Якщо тип гри не визначено, внесок 0%
    }

    effectiveContribution := betAmount * contributionRate
    b.Wager.CurrentProgress += effectiveContribution

    if b.Wager.CurrentProgress >= b.Wager.RequiredAmount {
        b.Status = Completed
        b.Wager.CurrentProgress = b.Wager.RequiredAmount // Запобігаємо переповненню
    }
}

Ми також повинні бути уважними до конкурентного доступу до b.Wager.CurrentProgress, якщо обробляємо ставки паралельно. Використання каналів або sync.Mutex буде доречним.

3. Bonus Wallet vs Real Wallet (Бонусний гаманець проти реального гаманця)

Це фундаментальне розрізнення у бонусному двигуні. Кошти гравця повинні бути чітко розділені.

  • Real Wallet (Реальний гаманець): Містить кошти, які гравець може вивести в будь-який момент. Вони не підлягають вейджер-вимогам.
  • Bonus Wallet (Бонусний гаманець): Містить бонусні кошти та виграші, отримані за рахунок бонусних коштів. Ці кошти заблоковані для виведення до повного відіграшу вейджера.

Правила використання:

  1. При розміщенні ставки, система спочатку використовує кошти з реального гаманця.
  2. Якщо реальних коштів недостатньо, або якщо це дозволено правилами бонусу, використовуються кошти з бонусного гаманця.
  3. Виграші від ставок, зроблених за реальні кошти, йдуть на реальний гаманець.
  4. Виграші від ставок, зроблених за бонусні кошти, йдуть на бонусний гаманець.
  5. Після повного відіграшу вейджера, кошти з бонусного гаманця переводяться на реальний гаманець.

Go-підхід: Структура UserWallet повинна чітко розділяти баланси. 

package bonusengine

import "sync"

type UserWallet struct {
    UserID        string
    RealFunds     float64
    BonusFunds    float64
    ActiveBonuses []string // ID активних бонусів
    mu            sync.Mutex // Для забезпечення потокобезпечності
}

// DebitFunds намагається списати кошти, спочатку з реального, потім з бонусного
func (uw *UserWallet) DebitFunds(amount float64) (debitedReal float64, debitedBonus float64, err error) {
    uw.mu.Lock()
    defer uw.mu.Unlock()

    if uw.RealFunds >= amount {
        uw.RealFunds -= amount
        debitedReal = amount
        return debitedReal, 0, nil
    }

    remainingAmount := amount - uw.RealFunds
    debitedReal = uw.RealFunds
    uw.RealFunds = 0

    if uw.BonusFunds >= remainingAmount {
        uw.BonusFunds -= remainingAmount
        debitedBonus = remainingAmount
        return debitedReal, debitedBonus, nil
    }

    return 0, 0, ErrInsufficientFunds // Припустимо, що ErrInsufficientFunds визначено
}

// CreditFunds додає кошти, залежно від джерела (чи була ставка зроблена за бонусні кошти)
func (uw *UserWallet) CreditFunds(amount float64, fromBonusStake bool) {
    uw.mu.Lock()
    defer uw.mu.Unlock()

    if fromBonusStake {
        uw.BonusFunds += amount
    } else {
        uw.RealFunds += amount
    }
}

// WithdrawBonus переводить бонусні кошти на реальний гаманець після відіграшу
func (uw *UserWallet) WithdrawBonus() {
    uw.mu.Lock()
    defer uw.mu.Unlock()

    uw.RealFunds += uw.BonusFunds
    uw.BonusFunds = 0
}

4. Bonus Expiration та Auto-Cancel

Бонуси не можуть бути вічними. Вони часто мають термін дії, після якого вони автоматично анулюються, якщо не були відіграні. Це запобігає “зависанню” бонусів і спрощує облік.

  • Expiration: Бонус має поле ExpiresAt (тип time.Time у Go).
  • Auto-Cancel: Система повинна мати механізм для регулярної перевірки та анулювання прострочених бонусів. Це може бути фоновий Go-routine, cron-job або event-driven підхід.

Go-підхід: Горутини та канали чудово підходять для створення фонових “прибиральників”. 

package bonusengine

// BonusExpirationService відповідає за обробку прострочених бонусів
type BonusExpirationService struct {
    bonusRepo BonusRepository // Інтерфейс для взаємодії з сховищем бонусів
    walletService WalletService // Інтерфейс для взаємодії з гаманцями
    stopCh      chan struct{}
}

func NewBonusExpirationService(repo BonusRepository, ws WalletService) *BonusExpirationService {
    return &BonusExpirationService{
        bonusRepo:   repo,
        walletService: ws,
        stopCh:      make(chan struct{}),
    }
}

func (s *BonusExpirationService) Start(interval time.Duration) {
    ticker := time.NewTicker(interval)
    defer ticker.Stop()

    for {
        select {
        case <-ticker.C:
            s.CheckAndExpireBonuses()
        case <-s.stopCh:
            return
        }
    }
}

func (s *BonusExpirationService) Stop() {
    close(s.stopCh)
}

func (s *BonusExpirationService) CheckAndExpireBonuses() {
    // Отримати всі активні бонуси, які прострочені
    expiredBonuses, err := s.bonusRepo.GetExpiredActiveBonuses(time.Now())
    if err != nil {
        // Логуємо помилку
        return
    }

    for _, bonus := range expiredBonuses {
        if bonus.Status == Active || bonus.Status == Wagering {
            // Анулювати бонус
            bonus.Status = Expired
            bonus.BonusFunds = 0 // Обнуляємо бонусні кошти
            s.bonusRepo.UpdateBonus(bonus) // Оновлюємо статус у сховищі
            s.walletService.RemoveBonusFundsFromWallet(bonus.UserID, bonus.Amount) // Списати кошти з гаманця
            // Логувати подію анулювання
        }
    }
}

5. Bonus Abuse Detection (Виявлення зловживань бонусами)

Це одна з найскладніших частин. Шахраї постійно шукають способи обійти правила. Детекція зловживань є ключовою для захисту прибутковості.

  • Multi-accounting: Створення кількох облікових записів для отримання одного і того ж бонусу багато разів.
  • Collusion: Змова між гравцями для маніпуляції ігровим процесом або бонусними умовами.
  • Exploiting system bugs: Використання вразливостей системи для отримання незаслужених бонусів.
  • Abuse of max bet rules: Розміщення ставок, що перевищують максимально дозволену суму під час відіграшу бонусу.

Go-підхід:

  • Моніторинг поведінки користувачів: IP-адреси, унікальні пристрої, моделі ставок.
  • Системи правил (Rule Engine): Завдання чітких правил, які тригерять підозрілі події.
  • Машинне навчання: Для складніших патернів аномалій.
  • Для Multi-accounting можна використовувати аналіз IP-адрес, email-адрес, номерів телефонів, даних пристроїв (device fingerprinting).

6. Max Bet Restrictions (Обмеження максимальної ставки)

Для бонусів з вейджером часто діє обмеження на максимальну ставку. Це не дозволяє гравцям швидко відіграти бонус, зробивши одну дуже велику ставку.

  • Приклад: Якщо максимальна ставка з активним бонусом становить 5$, то будь-яка ставка понад 5$ не буде врахована до вейджера або може призвести до анулювання бонусу.

Go-підхід: Перевірка максимальної ставки має відбуватися при кожній спробі розміщення ставки. 

package bonusengine

// CheckMaxBet перевіряє, чи не перевищує ставка максимально дозволену для активного бонусу
func (b *Bonus) CheckMaxBet(betAmount float64) error {
    if b.Status == Active || b.Status == Wagering {
        if maxBet, ok := b.Meta["max_bet"].(float64); ok {
            if betAmount > maxBet {
                return ErrMaxBetExceeded // Припустимо, що ErrMaxBetExceeded визначено
            }
        }
    }
    return nil
}

7. Audit Trail для Compliance (Аудиторський слід для відповідності)

У фінансових та ігрових індустріях суворе регулювання. Кожна дія, пов’язана з бонусами та коштами, повинна бути зафіксована. Це необхідно для:

  • Регуляторної відповідності: Демонстрація чесності та прозорості.
  • Вирішення спорів: Чітка історія транзакцій для розслідування скарг гравців.
  • Внутрішнього контролю: Моніторинг та аналіз роботи бонусної системи.

Що фіксувати:

  • Видача бонусу (коли, кому, який бонус, сума).
  • Зміна статусу бонусу (активація, відіграш, завершення, анулювання, прострочення).
  • Кожне оновлення прогресу вейджера (сума ставки, гра, внесок до вейджера).
  • Рух коштів між бонусним та реальним гаманцями.

Go-підхід: Використання структурованих логів (наприклад, з пакетами logrus або zap) та окремої таблиці/сервісу для аудиту. 

package bonusengine

import (
    "encoding/json"
    "log" // або logrus/zap
    "time"
)

type AuditLogEntry struct {
    Timestamp  time.Time              `json:"timestamp"`
    UserID     string                 `json:"user_id"`
    EventType  string                 `json:"event_type"` // e.g., "BONUS_ISSUED", "WAGER_PROGRESS_UPDATE", "BONUS_EXPIRED"
    EntityID   string                 `json:"entity_id"`  // ID бонусу, ID транзакції
    Details    map[string]interface{} `json:"details"`    // Специфічні дані події
}

// LogBonusEvent фіксує важливі події, пов'язані з бонусами
func LogBonusEvent(userID, eventType, entityID string, details map[string]interface{}) {
    entry := AuditLogEntry{
        Timestamp:  time.Now(),
        UserID:     userID,
        EventType:  eventType,
        EntityID:   entityID,
        Details:    details,
    }

    // Серіалізація в JSON для збереження або відправки в лог-систему
    logBytes, err := json.Marshal(entry)
    if err != nil {
        log.Printf("Error marshalling audit log entry: %v", err)
        return
    }

    // У реальному додатку це може бути відправка в Kafka, базу даних, або централізовану систему логів
    log.Printf("AUDIT: %s", string(logBytes))
}

// Приклад використання:
// LogBonusEvent(bonus.UserID, "BONUS_ISSUED", bonus.ID, map[string]interface{}{
//     "bonus_type": bonus.Type,
//     "amount": bonus.Amount,
//     "wager_multiplier": bonus.Wager.WagerMultiplier,
// })
// LogBonusEvent(bonus.UserID, "WAGER_PROGRESS_UPDATE", bonus.ID, map[string]interface{}{
//     "bet_amount": betAmount,
//     "game_type": gameType,
//     "old_progress": oldProgress,
//     "new_progress": bonus.Wager.CurrentProgress,
// })

Go’s Role in Building a Robust Engine

Go чудово підходить для розробки бонусного двигуна завдяки своїм основним перевагам:

  • Concurrency (Паралелізм): Go-рутини та канали дозволяють легко обробляти велику кількість одночасних запитів, виконувати фонові завдання (наприклад, перевірка прострочених бонусів) без блокування основного потоку. Це критично для систем з високим навантаженням.
  • Performance (Продуктивність): Go скомпільований, що забезпечує низьку затримку та високу пропускну здатність, що є важливим для фінансових транзакцій.
  • Strong Typing (Сильна типізація): Забезпечує чіткість даних та знижує ймовірність помилок, що є надзвичайно важливим у системах, що працюють з грошима.
  • Modularity (Модульність): Чистий дизайн Go, акцент на інтерфейсах, дозволяє легко розділяти компоненти (наприклад, BonusService, WalletService, AuditService), роблячи систему легшою для розуміння, тестування та підтримки.
  • Error Handling (Обробка помилок): Явна обробка помилок у Go сприяє написанню більш надійного коду, де кожен потенційний збій враховується.
  • Testing (Тестування): Простота написання юніт- та інтеграційних тестів у Go допомагає забезпечити коректність складної бонусної логіки.

Висновок

Побудова бонусного двигуна в Go — це захоплюючий, але складний проект. Він вимагає глибокого розуміння бізнес-логіки, уваги до деталей у розрахунках, ретельної архітектури для управління станами та коштами, а також потужних механізмів для виявлення зловживань та забезпечення відповідності.

Використовуючи потужні функції Go, такі як паралелізм, сильна типізація та модульність, ми можемо створити систему, яка є не тільки ефективною та масштабованою, але й надзвичайно надійною та безпечною. Пам’ятайте, що правильне нарахування бонусів — це не просто функціонал, це запорука довіри клієнтів та фінансової стабільності вашого бізнесу.

Що ви вважаєте найскладнішим аспектом у розробці бонусного двигуна? Поділіться своїми думками в коментарях!

Tags

go golang backend microservices fintech gaming softwarearchitecture bonusengine devto programming engineering

Similar Posts