Backend деңгээлинде промо жана бонустарды башкаруу

Макаланын толук тексти

💡 18+. Платформалар/операторлор жана провайдерлер үчүн инженердик-практикалык материал. оюнга чакыруу эмес. "Капчык" деп Ledger/Cüzdanı ACID кепилдиктери менен, "бонустар" деп оюндун балансына жана шарттарына таасир этүүчү промоферелерди түшүнөбүз.

1) Эмне үчүн өзүнчө backend промо алып

Акча инварианттары. Бонус ≠ "кошулган баланс": бул шарттар менен келишим (вейджер, оюндар боюнча депозит, максималдуу коюм/утуш).

Өзгөртүү ылдамдыгы. Маркетинг командалары күн сайын кампанияларды чыгарышат - бизге эрежелердин декларативдик кыймылдаткычы жана артка кайтаруу керек.

Анти-кыянаттык/комплаенс. KYC/RG/AML, velocity, сегментация, кымбат offers боюнча "төрт көз".

Байкоо жана отчеттуулук. SLO, промо наркы, GGR/NGR/LTV таасири.

Принцип: промо-ядро - өз статусу машиналары бар өзүнчө кызмат, ал эми акча капчык аркылуу гана жылат, идемпотент.

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

Deposit match (100% X чейин): депозиттин capture кийин эсептелинет, Veyjer X ×.

Cashback (Loss-Back): убакыт/оюн терезеси боюнча эсептелет, sticky/non-sticky болушу мүмкүн.

Free Spins/Free Bets: Спин/коюм баасы менен купондор/токендер, белгиленген RTP бассейн.

Тапшырмалар/миссиялар: тапшырма → прогресс → сыйлык.

Турнир/рейс-иш-чаралар: салым окуялар, рейтинг, байге.

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

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

3) бонустарды тейлөө архитектурасы


Admin (кампаниялар/эрежелер) ─ Promo API ─ Руль Engine/Eligibility
│
─ Bonus Ledger (офферлердин абалы)
─ Wagering Engine (прогресс)
─ Anti-Abuse (лимиттер/frod/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) Status машиналар жана сагалар

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

1. eligibility. текшерүү (сегмент, 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' (sticky эмес болсо) же чыгаруу боюнча чектөөлөрдү алып салуу.

emit `bonus. consumed`.

5. 4 Мөөнөтү/кайра чакыртып алуу

'expires _ at' же froda → 'revoke' эрежеси боюнча (демпотенттик), саясатка ылайык компенсация болушу мүмкүн.

6) капчык менен келишимдер (гана API аркылуу, ар дайым idempotent)

Бонусту чегер


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 промо кызматы (эталондор)

Offer түзүү (админ)


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"}

Прогресс Уэйджер (окуу)


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: өзүнөн-excluded/чеги алынып салынсын; per brand/аймак лицензия.

offers чыр-блок: бир эле учурда бир гана welcome бонус активдүү; артыкчылыктары.

Аномалия Detector: бир нече эсептер/түзмөктөр/ASN, тез "нөлгө" Уагер.

"Төрт көз" ири гранттар жана кол түзөтүүлөр.

WORM-аудит бардык өзгөртүүлөр эрежелери/гранттар/которуулар.

9) Байкоо, метрика жана SLO

SLO

`grant. issue p95` (issue→credited) ≤ 300–500 мс.

Жаңылоо 'wager _ progress p95' ≤ 200 ms учурдан тартып 'bet. settled`.

Окуялар 'bonus.' шинада p95 ≤ 2 мүнөт болгон.

"Жоголгон/кайталанган гранттар/конверсиялар" = 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 четке кагылган.

Trace: 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 мин.
Панелдер: offers/сегменттер боюнча конверсия, убакыт-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 жана анти-Frod кирет; ири суммадагы "төрт көз".
Outbox/CDC, DLQ жана башкарылуучу replay үчүн 'bonus.'.
SLO-dashboard, OpenTelemetry, WORM-аудит.
ROI жана комплаенс (RG/AML) үчүн DWH-Display.

Интеграция (RGS/капчык/CRM)

текшерүү max bet/win; бизнес ката кодун кайтарып жатам.
ыргытып 'trace _ id' жана 'idempotency _ key'.
Дедуп триггерлер жана жеткирүү кепилдиктери (webhooks кол коюлган).

14) Кызыл желектер (анти-үлгүлөрү)

Wallet айланып, түздөн-түз баланска "кол менен" бонус эсептөө.

Болбогон → кош гранттар/конверсиялар.

Weiger 'bet болуп эсептелет. placed 'жана' bet 'жыйынтыгы боюнча эмес. settled`.

Эч кандай contribution схемалар же алар провайдерлердин кодунда "тигилген".

Карама-каршы оффералар бир эле учурда активдештирилет.

Эч кандай velocity/анти-food жана WORM-аудит.

'bonus.' Окуялар outbox/CDC айланып жарыяланган.

Промо көрсөткүчтөрү Ledger/BI (ROI витриналары жок) менен дал келбейт.

15) Жыйынтык

Ишенимдүү backend промо - бул келишимдер жана инварианттар, "балансты кошуу" эмес. Ал эрежелерди акчадан ажыратат, иш жүзүндөгү жыйынтыктар боюнча прогрессти эсептейт, демпотенттүүлүккө жана байкоого кепилдик берет, бузукулуктан коргойт жана комплаенс менен камсыз кылат. Мындай негизги маркетинг тез жылып, оюнчу чынчыл шарттарды көрүп, каржы жана жөнгө салуучу ар бир offer наркынын жана таасиринин так сүрөтүн алат.