Оқиғалар мен наградаларды автоматтандыру: ережелер мен вебхактар

Геймификация екі «моторшыққа» сүйенеді: оқиғалар (пайдаланушы не істеді) және ережелер (ол үшін не керек). Бұл ауқымды және қателіксіз жұмыс істеуі үшін оқиғалардың сенімді шинасы, ереже қозғалтқышы, марапаттарды жеткізу/беру механизмі және фродтан қатаң қорғау қажет. Төменде - практикалық сәулет, үлгілер және чек парақтары.

1) «Оқиға → ереже → марапат» ағынының архитектурасы

1. Ingest (оқиғаның кірісі): SDK/web, төлем/ойын провайдері → API Gateway → кезек/шина (Kafka/Rabbit/Cloud Pub/Sub).

2. Normalizer: валидация, байыту (geo, device, payer_flag), схема нұсқасы.

3. Rules Engine: көзілдірік/ХР, миссияларды/квесттерді тексеру, марапаттар/хабарламалар триггерлері.

4. Reward Orchestrator: марапатты есептеу, бюджет-чек, RG/KYC-гейттер, «беру тапсырмасын» жасау, журналға жазылу.

5. Payout/Bonus Service: кэш/бонус-кэш/фриспиндер/купондар, сыртқы вебхактар (әмиян, провайдерлер).

6. Notifier: push/in-app/email/жиілік лимиттері бар мессенджерлер.

7. Storage/Analytics: шикі оқиғалар, витриналар, A/B, алерталар.

8. Anti-Fraud/RG: капалар, эвристика/ML, hold-and-review ірі сыйлықтар.

2) Оқиғалар моделі (ең аз жиынтық)

json
{
"event_id": "d9e8-...-5c2",  "event_name": "bet",  "version": "1. 2. 0",  "ts": "2025-10-24T11:37:21Z",  "user": {
"id": "u_123",   "geo": "TR",   "platform": "android",   "payer_flag": true,   "risk_flags": ["vp_nightly"]
},  "context": {
"session_id": "s_789",   "device_fp": "fp_...",   "ip": "203. 0. 113. 24"
},  "payload": {
"game_id": "slot_wolf",   "bet": 0. 5,   "win": 1. 25,   "currency": "EUR",   "provider": "GameCo"
}
}

Базовые типы: `login`, `session_start/end`, `bet/spin`, `win`, `deposit`, `withdraw_request`, `kyc_status_changed`, `mission_view/join/progress/complete`, `tournament_join/score/update/reward`, `reward_issued`, `rg_event`.

3) Ережелер қозғалтқышы: логиканы қалай сипаттау керек

Тұжырымдамалар: ережелер (if/then), сегменттер, уақыт терезелері, басымдық, нұсқалау.

Декларативтік ереженің мысалы (YAML-стиль):

yaml rule_id: r_points_winmult_v2 when:
event_name: bet filters:
- payload. bet >= 0. 2
- user. geo in ["TR","BR","PE"]
- now between "2025-11-01" and "2025-11-30"
score:
formula: "floor((payload. win / payload. bet) 3)"
caps:
per_bet: 50 per_minute: 200 per_day: 1500 reward_trigger:
on_progress:
threshold: [100, 300, 800]
reward: [{type: "fs", value: 10}, {type: "bonus_cash", value: 2}, {type: "loot", rarity: "rare"}]
guardrails:
kyc_min_level: 2 rg_limits_ok: true budget_pool: "nov_season"
budget_soft_cap: 80000 meta:
version: "2. 0"
experiment: "scoring_ab_2025w45"

4) Вебхактар: интеграция сервер-сервері

4. 1. Шығыс вебхоктар (провайдерлерге/әмиянға)

Әдісі: 'POST https ://partner. example/payouts`

Подпись: `X-Signature: HMAC-SHA256(secret, body)` + `X-Request-Id` (idempotency).

Ретраилер: экспоненциалды backoff, 'max _ retries = 8', jitter, DLQ.

Idempotency: қайталау сол 'X-Request-Id' → серіктес сол 'payout _ id/status' жауап беруге міндетті.

Payload мысалы:

json
{
"request_id": "rid_7f5...",  "user_id": "u_123",  "reward": {"type":"cash","amount":10. 00,"currency":"EUR"},  "reason": "milestone_300_points",  "kyc_level": 2,  "constraints": {"wagering": 0, "expiry_at": "2025-12-01T00:00:00Z"}
}

4. 2. Кіріс веб-хаттар (сізге)

Тек IP/MTLS тізімдеріне рұқсат етіңіз, HMAC және қолтаңбаның өмір сүру уақытын тексеріңіз ('X-Timestamp', ± 5 минут).

«Шикі» body + тақырыптарын аудит-қоймасында (WORM) сақтаңыз.

Кез келген дубль/қайталау → журналға қарсы idempotency key.

5) Сенімділік: екі есе төлемсіз «тегіс» ағын

At-least-once ingest + idempotent өңдеушілер → алтын стандарт.

Idempotency key: 'hash (event_id + user_id + rule_id)' ұпай есептеу үшін; сыйлық беру үшін жеке кілт 'reward _ task _ id'.

Exactly-once семантикасы көлікпен емес, тек логикалық тұрғыдан ғана шынайы.

Оқиғалар реті: 'event _ ts' және 'ingest _ ts'; 'user _ id' кілті бойынша кезектен reordering window (мысалы, 60 сек) және replay қолданыңыз.

Dead Letter Queue (DLQ):

Онда перманенттік қатесі бар хабарламалар жазамыз (уақытша схема өтпеді, қолтаңба дұрыс емес, бюджет жабылды).
reprocess/drop/fix schema батырмалары бар «DLQ ревю» қызметі.

6) Бюджеттер және маржаны қорғау

Бюджет пулдары: 'nov _ season', 'daily _ sprint', 'vip _ weekend'.

Квоталар: soft/hard cap, «circuit breaker» - бюджеттің 90% жеткен кезде ірі сыйлықтарды hold-state-ке аудару.

Бірыңғай құны: 'Prize & Bonus Cost per Active/Payor', Net Uplift.

Басымдықтары: RG және комплаенс промо маңыздырақ - жанжал кезінде награда кейінге қалдырылады.

Бюджетті тексеру мысалы (SQL-скетч):

sql
SELECT pool_id,    SUM(amount) AS spent,    budget AS limit,    SUM(amount)/budget AS fill
FROM reward_ledger
WHERE pool_id =:pool AND date(ts) = current_date
GROUP BY pool_id, budget;

7) RG/KYC/Geo-гейттер (ойыншының қауіпсіздігі және комплаенс)

KYC: кэш/ірі сыйлықтар үшін минимум L2; фриспиндер L1 рұқсат етіледі.

RG: депозит лимиттерін тексеру, өзін-өзі алып тастау, «cool-off» → марапаттар шектеулер алынғанға дейін «мұздатылады».

Geo: әр ереже/марапаттар пулы үшін рұқсат етілген елдердің тізімі.

Шекті тәуекелдер: жеке аккаунттарда күрт өсу «іс жүзінде жетті» = hold & review.

8) Антифрод-ереже және телеметрия

/ мин/сағ/тәулік ставкасы бойынша көзілдірік қапшықтары, ставкалардың ең төменгі дисперсиясы, «мінсіз» паттерндерге тыйым салу.

Техсигналдар: headless, қайталанатын device_fp, прокси-субжелілер.

Аномалиялар: «көзілдірік/ставка» және «көзілдірік/мин» - 99-перцентильдегі ұзын «құйрықтар».

Топ-жүлдегерлер үшін Hold-and-review: KYC автоматты чек + қолмен қарау.

9) Мониторинг, метрика және аллергия

SLO/SLA:

Ingest p95 ≤ 250 мс; p95 ≤ 150 мс ережелерді өңдеу; көшбасшы бортты жаңарту ≤ 2 с; сыйлық беру ≤ 60 с.
Error budget < 0. 1% оқиғалар/тәулік.

Алерталар:

Эксперименттерде SRM (трафиктің ауытқуы), DLQ өсуі, HMAC-валидация қолтаңбасының құлдырауы, бюджеттің артуы, idempotent-дубльдердің көтерілуі.

Дашборд (күн сайын):

Оқиғалар/с, лаг, істен шығуға төзімділік;
Воронка: оқиға → ереже → reward_task → reward_issued;
Құны: Prize/Bonus per Active, Net Uplift;
Сапасы: фрод-жалаулар, KYC-блоктар, RG-іске қосулар.

10) Нұсқалау және көші-қон

Әрбір ереже - versioned ('rules. version`).

Белсенді ережені жаңа нұсқасыз өңдеуге болмайды; фичефлаг және «тегіс қыздыру» пайдаланыңыз (10% → 50% → 100%).

Оқиғалар схемасы schema registry арқылы; сыйыспайтын өзгерістер - тек major нұсқасы.

11) A/B-автоматтандыру тестілері (қысқаша)

Бірлік - пайдаланушы; sticky-assignment; стратификация (payer/geo/platform).

Интерференцияны болдырмау үшін бөлек көшбасшы борттар немесе көзілдіріктерді қалыпқа келтіру.

Primary: participation_net, completion, Net ARPPU; Guardrails: шағымдар/1k, фрод жалаулар, RG іске қосу.

CUPED және дисперсияны төмендетуге арналған ковариаттар.

12) Мысалдар: қағидадан беруге дейін

12. 1. Триггер «прогресс үшін микро-марапат»

json
{
"type": "reward_task. created",  "reward_task_id": "rt_456",  "user_id": "u_123",  "origin": {"rule_id":"r_points_winmult_v2","threshold":300},  "reward": {"type": "bonus_cash", "amount": 2, "currency":"EUR", "wagering": 15},  "pool_id": "nov_season",  "status": "pending",  "created_at": "2025-10-24T11:38:30Z"
}

12. 2. Әмиянға шығатын вебхук


POST /wallet/credit
X-Request-Id: rid_7f5...
X-Timestamp: 1730061700
X-Signature: sha256=7b9a...

{ "user_id":"u_123", "amount":2. 00, "currency":"EUR", "reason":"rule:r_points_winmult_v2" }

→ 'reward _ task' = 'succeeded' және 'reward _ ledger' дегенге жазу.

Сәтсіздік (5хх/таймаут) → ретрай сол 'X-Request-Id'.

Сәтсіздік (4xx) → DLQ + қолмен талдау.

13) Қоймалар мен кестелер (скетч)

sql
-- наградалар журналы
CREATE TABLE reward_ledger (
id BIGSERIAL PRIMARY KEY,  reward_task_id TEXT UNIQUE,  user_id TEXT,  pool_id TEXT,  type TEXT,  value NUMERIC(18,2),  currency TEXT,  cost NUMERIC(18,2) DEFAULT 0, -- реальная стоимость для P&L status TEXT, -- succeeded/failed/held created_at TIMESTAMPTZ,  updated_at TIMESTAMPTZ
);

-- индемпотенттілік
CREATE UNIQUE INDEX uniq_reward_task ON reward_ledger (reward_task_id);

-- бюджет
CREATE TABLE reward_budget (
pool_id TEXT PRIMARY KEY,  budget NUMERIC(18,2),  spent NUMERIC(18,2),  period DATE
);

14) Қауіпсіздік және құпиялылық

HMAC-қолтаңбалар, MTLS, allow-list IP.

Транзиттегі/тыныштықтағы шифрлау, кілттерді ротациялау, vault құпиялары.

Payload деректерін барынша азайту (PII жеке, сілтеме-токен бойынша, TTL).

Өзгермейтін аудит-логтар (WORM).

Сақтау және жою саясаты (ұмыту құқығы, deduplication-safe).

15) Ұшырудың чек-парағы

Оқиғалар мен registry схемалары, вебхук келісімшарттары (сигнатуралар, TTL).
Кезектер, ретрациялар, DLQ, демпотенттік өңдегіштер.
Ережелердегі қақпалар/гвардrail, KYC/RG-гейттер.
Бюджет-пулдар, circuit-breakers, толу тәуекелдері.
Дашборд SLO + воронка reward.
A/B-фичефлагтар және SRM-мониторинг.
Оқиғалар Runbook (қайта ойнату, қатыру, қолмен беру).

16) Шағын кейс (синтетикалық)

Ойын провайдерлері мен әмиян оқиғалары қосылды; «win/bet» қосулы.

Вебхуктарға HMAC, 8-ге дейін ретраға қол қойылды, DLQ әрбір 2 сағ.

4 апта ішінде: өңдеу мерзімі p95 180 мс; DLQ < 0,06%; төлем құжаттары 0; фрод-жалаулар − 0,4 п.т.; ΔParticipation_net +6,3 п.п.; ΔARPPU (net) +€2,1 при Prize&Bonus/Active +€0,7.

Қорытынды: ережелерді жергілікті бюджет-пулдары бар жаңа геоға масштабтау.

Марапаттарды автоматтандыру - «фриспиндермен жіберу» емес. Бұл инженерлік жүйе: оқиғаларды сенімді жеткізу, ережелерді қатаң нұсқалау, idempotency және қолтаңбалар, бюджет-каперлер, KYC/RG-гейттер, антифрод және мониторинг. Бұл қаңқаны бір күні тұрғызыңыз - кез келген миссиялар, турнирлер мен «лут-сәттер» болжамды, уақтылы және оң нетто-эффектімен жұмыс істейтін болады.