Backend деңгейінде промо және бонустарды басқару

Мақаланың толық мәтіні

💡 18+. Платформалар/операторлар және провайдерлер үшін инженерлік-практикалық материал. Ойынға шақыру емес. «Әмиян» деп ACID-кепілдіктері бар Ledger/Wallet, «бонустар» деп ойын балансы мен шарттарына әсер ететін промофераларды түсінеміз.

1) Не үшін промо жеке backend шығаруға

Ақша инварианттары. ≠ бонусы «теңгерімге қосылған»: бұл шарттары бар келісімшарт (вейджер, ойындар бойынша салым, ең жоғары ставка/ұтыс).

Өзгерістер жылдамдығы. Маркетинг командалары күнделікті науқандар шығарады - декларативті ережелер мен кері қайтару қозғалтқышы қажет.

Анти-абьюз/комплаенс. KYC/RG/AML, velocity, сегментация, қымбат офферлер үшін «төрт көзді» тасу.

Бақылау және есеп беру. SLO, промо құны, GGR/NGR/LTV әсері.

Принцип: промо-ядро - жеке мәртебелі машиналары бар жеке сервис, ал ақша тек әмиян арқылы, идемпотенттік түрде қозғалады.

2) Бонустар мен инварианттар типологиясы

Deposit match (100% X дейін): capture депозиттен кейін есептеледі, вейджер X ×.

Cashback (жоғалту-бэк): уақыт/ойындар терезесі бойынша есептеледі, sticky/non-sticky болуы мүмкін.

Free Spins/Free Bets: купондар/белгілер спин/ставка үшін прайс, бекітілген RTP-пул.

Квесттер/миссиялар: тапсырма → прогресс → марапат.

Турнирлер/рейс-ивенттер: оқиғалар үлесі, рейтинг, жүлделі.

Инварианттар:

Sticky: шарттарды орындағанға дейін шығару мүмкін емес.
Max bet/Max win: бонустық қаражаттан ставкаға/төлемге арналған лимиттер.
Contribution: ойындар бойынша салым (мысалы, slots = 100%, live = 10%).
Expiry: бонус мерзімі және вейджер терезесі.

3) Бонустар сервисінің архитектурасы


Admin (науқандар/ережелер) ─ Promo API ─ Rules Engine/Eligibility
│
─ Bonus Ledger (офферлердің жай-күйі)
─ Wagering Engine (прогресс)
─ Anti-Abuse (лимиттер/фрод/velocity)
└─Outbox (events) ─Kafka/Pulsar ─BI/DWH/CRM

Wallet/Ledger── Idempotent Commands ───┘

Rules Engine - декларативтік шарттар (сегменттер, гео/лицензия, арналар, KYC/RG).

Wagering Engine - 'bet. settled`/`wallet. debit	credit`.
Bonus Ledger - бонустардың/миссиялардың жай-күйі бойынша ақиқат көзі.
Outbox/CDC - сенімді жарияланым 'bonus. issued	progress. updated

4) Деректер моделі (жеңілдетілген)

`bonus_grant`

`grant_id, player_id, offer_id, type, currency, amount_minor, sticky, wager_x, max_bet_minor, max_win_minor, contribution_schema_id, status (issued	active	paused	completed	expired	revoked), issued_at, expires_at, brand_id, region, idempotency_key`

`wager_progress`

`grant_id, required_minor, contributed_minor, remaining_minor, last_update_at`

`contribution_schema`

`schema_id, rules: [{game_type:"slot", pct:100},{game_type:"live", pct:10}]`

'bonus _ ledger _ entry' (аудит)

`entry_id, grant_id, action (issue	consume	revoke	expire	adjust), amount_minor, reason, occurred_at, trace_id`

5) Статустық машиналар мен сагалар

5. 1 Беру (issue) - сага

1. eligibility. check (сегмент, RG/KYC, velocity)

2. grant. create (status=`issued`)

3. wallet. credit [bonus] (демпотенттік; sticky кезінде - бонустық суб-балансқа)

4. activate (status=`active`)

5. emit `bonus. issued`

Rollback: 3 қадамда құлаған кезде → 'grant. cancel '+ оқиға' bonus. revoked`.

5. 2 Вейджердің ілгерілеуі

Na 'bet. settled '=' stake _ minor contribution_pct' салымын санау (немесе win/loss ережелері бойынша).

'wager _ progress' атомарлы түрде жаңарту; 100% -ға жеткенде - 'complete'.

5. 3 Аяқтау (consume)

complete → `wallet. convert_bonus_to_cash' (егер non-sticky болса) немесе шығару шектеулерін алып тастау.

emit `bonus. consumed`.

5. 4 Аяқталуы/кері қайтарылуы

'expires _ at' немесе → 'revoke' (демпотенттік) фрод ережесі бойынша саясатқа сәйкес өтемақы болуы мүмкін.

6) Әмиянмен жасалған келісімшарттар (тек API арқылы, әрқашан демпотенттік)

Бонусты есептеу


POST /v1/wallet/credit
Headers: X-Idempotency-Key: bonus_grant_123
{
"player_id":"p_001",  "amount":{"minor_units":100000,"currency":"EUR"},  "balance_type":"bonus",  "reference":{"grant_id":"gr_123","offer_id":"of_777"}
}
→ 200 {"status":"credited","entry_id":"e_9001"}

Шарттар орындалғаннан кейін кэшке айналдыру


POST /v1/wallet/convert
Headers: X-Idempotency-Key: bonus_convert_gr_123
{
"player_id":"p_001",  "from_balance":"bonus",  "to_balance":"cash",  "amount_minor":100000,  "reference":{"grant_id":"gr_123"}
}
→ 200 {"status":"converted","entry_id":"e_9010"}

Тексеру max bet/max win - RGS/Wallet Guard жағында:

'bets. authorize 'кодымен қабылданбайды' BONUS _ MAX _ BET _ EXCEEDED '.

7) Промо сервисінің API (эталондар)

Оффер құру (әкімші)


POST /v1/offers
{
"name":"Welcome 100% up to 100€",  "type":"deposit_match",  "params":{"match_pct":100,"cap_minor":10000,"wager_x":20,"sticky":true,       "max_bet_minor":200,"max_win_minor":50000,"contribution_schema_id":"c_slot100_live10"},  "eligibility":{"brands":["A"],"regions":["EU"],"segment":"new_depositors"},  "schedule":{"start":"2025-10-20T00:00:00Z","end":"2025-11-30T23:59:59Z"}
}
→ 201 {"offer_id":"of_777"}

Бонусты беру (runtime)


POST /v1/bonus/grants
Headers: X-Idempotency-Key: grant_p001_of777
{
"player_id":"p_001","offer_id":"of_777","trigger":"deposit_captured","amount_minor":10000
}
→ 200 {"grant_id":"gr_123","status":"active"}

Вейджердің ілгерілеуі (read)


GET /v1/bonus/grants/gr_123/progress
→ 200 {"required_minor":200000,"contributed_minor":45000,"remaining_minor":155000,"pct":0. 225}

Күшін жою/кері қайтару


POST /v1/bonus/grants/gr_123/revoke
Headers: X-Idempotency-Key: revoke_gr_123
{ "reason":"fraud_velocity" }
→ 200 {"status":"revoked"}

Барлық write-қоңыраулар - 'X-Idempotency-Key' және 'X-Trace-Id'.

8) Анти-абьюз және комплаенс

Velocity лимиттері: депозитті беру/конверсиялау/әрекеттер (Redis counters + TTL + Lua).

Триггерлердің дедуп: бір депозит → ереже бойынша бір грант.

Сегментация және RG: self-excluded/лимитті алып тасталсын; per brand/region лицензиясы.

Офферлер қайшылығы блогы: бір уақытта тек бір welcome бонусы белсенді; басымдықтар.

Аномалиялар детекторы: бірнеше аккаунттар/құрылғылар/ASN, вейджердің жылдам «нөлденуі».

Ірі гранттар мен қолмен түзетулерге арналған «Төрт көз».

WORM-аудит ережелердің/гранттардың/конверсиялардың барлық өзгерістері.

9) Бақылау, метрика және SLO

SLO (бағдарлар):

`grant. issue p95` (issue→credited) ≤ 300–500 мс.
'wager _ progress p95' ≤ 'bet' сәтінен бастап 200 мс жаңарту. settled`.
Оқиғадан бастап p95 ≤ 2 мин шинадағы 'bonus.' оқиғалары.
«Жоғалған/қайталанған гранттар/конверсиялар» = 0.

Өлшемдері:

Rate/latency по `issue/convert/revoke`, error-rate (business/4xx/5xx), `IDEMPOTENCY_MISMATCH`.
Вейджердің конверсиясы, орташа 'time-to-complete', мерзімі өткен үлесі.
Промо құны: когортадағы 'promo _ cost' (minor) және 'promo _ roi'.
Анти-абьюз: velocity іске қосылуы, ауытқыған max bet/win.

Трейсинг: OpenTelemetry 'trigger → grant → wallet тізбегі бойынша. credit → progress. update → convert`.

10) RGS/ойындармен интеграциялау

Free Spins/Free Bets купондары - 'entitlements' API арқылы: токендерді беру, рантаймда есептен шығару, пайдалану бойынша телеметрия.

Max bet/win - 'bets. authorize` и `bets. settle`; 'BONUS _ RULE _ VIOLATION' кодтарын қайтарыңыз.

Contribution - 'bet' деңгейіндегі сұлба. settled '(' game _ type/provider _ id 'бойынша), схемалар нұсқасы.

11) DWH/BI және есептер

Outbox оқиғалар → Lake (bronze) → Silver (дедуп, SCD2) → Gold витриналар:

`fact_bonus_grants`, `fact_wager_progress`, `fact_bonus_cost`, `fact_promo_roi`.
Жас SLA: Silver ≤ 15 мин, Gold ≤ 30-60 мин.
Панельдер: оффералар/сегменттер бойынша конверсия, time-to-complete, ойындар бойынша салым, абьюз-инциденттер.

12) Қауіпсіздік және резиденттік

mTLS + OAuth2 CC; scope’ы `promo:issue`, `promo:convert`, `promo:revoke`.

Кілттер/токендер - per brand/region, қысқа тұратын; Vault/HSM құпиялары.

PII-оқшаулау: 'player _ id' - бүркеншік ат; RLS по `brand/region`.

Rate limits және беруге квоталар; ретрайлардың дауылынан қорғау.

13) Чек парақтары

Платформа/оператор

Барлық ақша операциялары 'Idempotency-Key' -мен Wallet арқылы өтеді.
Rules/Eligibility нұсқаланады; көші-қон оқиғаларының «қос хаты».
Contribution-схемалар орталықтандырылған, тесттермен жабылған.
Velocity және анти-фрод қосылған; ірі сомаға «төрт көз».
Outbox/CDC, DLQ және 'bonus.' үшін басқарылатын replay.
SLO-дашбордтар, OpenTelemetry, WORM-аудит.
ROI және комплаенс (RG/AML) үшін DWH-витриналар.

Интеграция (RGS/әмиян/CRM)

max bet/win; бизнес қате кодын қайтарамын.
'trace _ id' және 'idempotency _ key'.
Триггерлер дедупі және жеткізу кепілдіктері (webhooks қол қойылған).

14) Қызыл жалаулар (қарсы үлгілер)

«Қолмен» бонусты Wallet-ті айналып өтіп, тікелей теңгерімге есептеу.

Теңсіздіктің болмауы → қосарлы гранттар/конверсиялар.

Вейджер 'bet' деп саналады. 'bet' нәтижесі бойынша емес, placed '. settled`.

contribution схемалары жоқ немесе олар провайдерлер кодында «қорғалған».

Қайшылықты офферлер бір уақытта іске қосылады.

Velocity/анти-фрод және WORM-аудит жоқ.

'bonus.' оқиғалары outbox/CDC бағдарламасын айналып өтіп жарияланады.

Промо көрсеткіштері Ledger/BI-мен сәйкес келмейді (ROI витриналары жоқ).

15) Қорытынды

Сенімді backend промо - бұл «теңгерімді қосу» емес, келісімшарттар мен инварианттар. Ол ережелерді ақшадан ажыратады, нақты нәтижелер бойынша прогресті есептейді, демпотенттілік пен бақылауға кепілдік береді, абьюзден қорғайды және комплаенсті қамтамасыз етеді. Мұндай өзекпен маркетинг жылдам жүреді, ойыншы әділ жағдайды көреді, ал қаржы мен реттеушілер әрбір оффердің құны мен әсерінің нақты көрінісін алады.