API джекпот жүйелері қалай жұмыс істейді

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

💡 18+. Материал - ойынға шақырусыз инженерлік-қолданбалы. Терминдер: платформа - PAM/әмиян/касса/бонустар/RG; RGS - Remote Game Server (студия ойындарының өзегі); агрегатор - RGS жиыны үшін біріздендірілген қабат; JP - jackpot-сервис.

1) Джекпот жүйесі дегеніміз не және ол экожүйеде қайда тұрады

Джекпот жүйесі - мөлшерлемелерден жарналар жинайтын, ұтыс пулдары мен триггерлерін басқаратын, жүлделерді бөлуді есептейтін және оператордың төлем контуры арқылы төлемдерді бастайтын жеке сервис (кейде сервистер кластері). Ол біріктіріледі:

RGS (ставкалар/нәтижелер және біліктілік туралы хабарламалар), платформа/әмиян (жарналарды есептен шығару және ұтыстарды кредиттеу), агрегатормен (көптеген студиялардан/брендтерден роутинг), BI/реттегішпен (телеметрия және есептілік).

2) Джекпоттардың түрлері (және API-де не өзгереді)

1. Тіркелген (Fixed): алдын ала белгілі жүлде сомасы. API-де пул жоқ, тек шарттар мен несиені тексеру.

2. Прогрессивті (Progressive): пул мөлшерлеме жарналарынан өседі. Жарнаның эндпоинттары мен ағымдағы мөлшерін жариялау қажет.

3. Көп деңгейлі (Multi-tier: Mini/Major/Grand): әртүрлі мүмкіндіктері мен каптары бар бірнеше параллель пулдар.

4. Жергілікті vs желілік: жергілікті пул - бір операторда/брендте; желілік - көптеген операторлар/брендтер/өңірлер бойынша жиынтық (мультитенанттылық және репликация сыни).

5. Уақытша/нақты: мерзімдік немесе кесте бойынша пул (таймерлер мен авто-ұтыстар қажет).

3) Ақша инварианттары

Баланс шындығының көзі - әмиян/ledger платформасы. JP тек пулдар мен міндеттемелердің жай-күйін сақтайды.

Барлық ақша операциялары - іспеттес (кілттер 'jp _ contrib _ id', 'jp _ trigger _ id', 'jp _ payout _ id').

«Жоғалған/қайталанған төлемдер» = 0. Өтемақылар - ДБ-ны қолмен түзетпейтін оқиғалармен (сағалармен) ғана.

Жарнаны (contribution), триггерді (trigger) және төлемді (payout) өз телеметрияңызбен дербес транзакциялар ретінде бөліңіз.

4) Эталондық келісімшарттар API

4. 1 RGS/агрегатор → JP (жарналар мен триггерлер)

'POST/v1/jp/contributions' - пулға жарнаны есепке алу

json
{
"jp_contrib_id": "uuid-1",  "tenant_id": "brand-42",  "pool_id": "grand-eu-01",  "player_id": "p_abc",  "game_id": "studio:slot_777",  "round_id": "r_123",  "bet": {"amount": 2. 00, "currency": "EUR"},  "contrib": {"amount": 0. 02, "currency": "EUR"},  "occurred_at": "2025-10-23T15:12:05Z",  "idempotency_key": "round_r_123"
}

'POST/v1/jp/candidates' - қатысуға өтінім/шарттарды тексеру (қосымша)

Жауап: 'eligible: true/false', салмақ немесе мүмкіндік, ережелер.

'POST/v1/jp/triggers' - іске қосылу фактісін тіркеу

json
{
"jp_trigger_id": "uuid-2",  "pool_id": "grand-eu-01",  "reason": "random_hit",  "selector": {"player_id": "p_abc", "round_id": "r_123"},  "occurred_at": "2025-10-23T15:12:06Z",  "idempotency_key": "jp_t_grand_r_123"
}

💡 Ескертпе: кейбір модельдерде триггердің бастамашысы JP (ішкі рулетка), ал RGS раунд туралы ғана хабарлайды. Онда 'triggers' JP → платформасына шақырылады, ал RGS оқиғаға жазылады.

4. 2 JP → платформа (төлемдер/резервтер)

'POST/v1/wallet/reserve' - (қосымша) болашақ төлемге арналған резерв

'POST/v1/wallet/credit' - ойыншыға ұтыс кредиті

json
{
"jp_payout_id": "uuid-3",  "tenant_id": "brand-42",  "player_id": "p_abc",  "pool_id": "grand-eu-01",  "amount": {"amount": 500000. 00, "currency": "EUR"},  "meta": {"tax": "withheld=false", "tier": "grand"},  "idempotency_key": "jp_p_grand_r_123"
}

Платформаның жауаптары: 'credit. ok	failed ', себептер кодтарымен (RG/AML, шығару лимиттері, санкциялар, гео-блок).

4. 3 Пулдың мәртебесін жариялау (майдандар/виджеттер үшін)

'GET/v1/jp/pools/{ pool _ id}' → ағымдағы өлшемі, seed, kap, қатысушылар саны, ETA және т.б.

'GET/v1/jp/pools' → сүзгілері бар бренд/өңір бойынша пулдар тізімі.

5) Оқиғалық модель (Kafka/Pulsar) және схемалар

Негізгі топиктер:

`jp. contribution. recorded`
`jp. pool. updated '(өлшемі, бәсекелес жаңартулары)
`jp. triggered`

`jp. payout. requested	credited	failed`
`wallet. credit. '(сағаларға арналған айна)
`rg. limit. hit`, `aml. alert. opened '(егер төлем бұғатталса)
`audit. config. changed '(лимиттер, seed, cap, бөлу)

Келісімшарттар: Euro/JSON Schema + Schema Registry, «tenant _ id», «pool _ id», «player _ id» партияландыру кілттері. Нұсқалау - backward-compatible.

6) Триггер алгоритмдері (жоғары деңгейлі)

Ықтималдық (p-тұрақты): әрбір білікті раундқа 'p' ықтималдығымен (пулға/деңгей типіне байланысты) hit генерациялаймыз.

Диапазондық (must-drop): пул cap-сомаға немесе мерзімге дейін құлауға міндетті - ішкі randomды [min, max] диапазонында сақтаймыз, cap/ETA жариялаймыз.

Sid- және entropy-басқару: серверлік seed + per-round salt; джекпоттарға арналған клиенттік орындардан бас тарту. Барлық seed өзгерістері WORM аудитінде.

Адалдық: триггер ойыншының нақты тұлғасына байланысты болмауы тиіс (гео/лицензия/біліктілік қағидаларынан басқа). Кез келген «дербес» таргеттеу - табу.

7) SLO және өнімділігі

p95 'contribution' <120 мс, p99 <250 мс.

p95 'trigger → credit' <500 мс (сыртқы төлем хопсыз).

«Жоғалған/қайталанған төлемдер» = 0 (келісімшарттық тесттермен тексеріледі).

Оқиғаларды BI-ға жеткізу ≤ 5 минут.

Критикалық жолдар үшін JP API қолжетімділігі ≥ 99. 95%.

8) Қауіпсіздік және комплаенс

mTLS + барлық S2S-шақыруларда қолтаңбалар (HMAC/EdDSA); қысқа өмір сүретін токендер.

Zero-trust: желілік саясат/mesh, ең төменгі артықшылықтар, өңірлер бойынша сегменттеу.

WORM-аудит өзгерістерінің лимиттері, формулалары, seed/entropy, пулдар пішіндері.

GDPR/Data residency/PCI: PII және логи - өңірде; сезімтал өрістерді токенизациялау; кросс-өңірлік оқуларға тыйым салу.

RG/AML: төлемдегі синхронды тоқтату сигналдары; SAR/STR-түсіру автоматтандырылған.

9) Келісімділік және сағалар

Жарна ('contribution') - JP-де бекітеміз, jp жариялаймыз. contribution. recorded`.

Триггер ('triggered') - міндеттемені жасайды; JP 'payout' сағатын іске қосады.

Төлем ('payout. requested → wallet. credit. ok ') - саганы аяқтайды; фейле кезінде - дедупликациямен ретра.

Outbox/CDC - оқиғаларды жариялаудың жалғыз жолы; «айналма» логгерлер жоқ.

10) Телеметрия және дашбордтар

Бизнес:

`pool_size`, `contrib_rate`, `avg_contrib_per_bet`, `time_to_drop`, `payouts_count/sum`, `tier_distribution`.

Техникалық:

p50/p95/p99 по `contribution`, `trigger`, `payout`;
error rate с типами (5xx/4xx/business), retry storms, queue lag;
`wallet. credit` latency/ok-rate; пулды жаңарту қайшылығы.

Алерталар:

'payout. failed '> X% бренд/аймақ бойынша,' pool _ size '> cap - Y% уақыт (конфигурация қатесі), drift' pool _ size 'және салыстыру бойынша жарналар сомасы арасындағы> Z ppm.

11) Мультитенанттық және оқшаулау

Барлық сұраулар мен оқиғалар 'tenant _ id/brand _ id/license/region' деп белгіленген.

Жергілікті/желілік пулдар әртүрлі лицензиялар/өңірлер кезінде физикалық (DB/cluster) бөлінген.

Row-level security (RLS) және BI витриналарында бүркемелеу.

Бренд/өңірге арналған жеке кілттер/құпиялар және схемалық кеңістіктер.

12) Бонустармен/турнирлермен интеграциялау

Жарналар вейджерді тікелей ұлғайтпайды; бонусқа салым - жарнадан емес, мөлшерлемеден келеді.

Турнирлер «JP-ге қатысқаны» немесе «топ-салымдарға түскені» үшін ұпай жинай алады. 'jp оқиғасы. contribution. recorded` и `jp. triggered`.

Міндетті ереже: джекпот-механик базалық RTP ойынын өзгертпейді; әйтпесе жеке сертификаттау қажет.

13) Тестілеу және хаос-практика

Келісімшарттық тесттер RGS, JP, әмиян: дубль-жеткізу, кідірістер, out-of-order, rollback.

Жүктеме тестілері: ставкалар мен триггерлердің дауылы, пулдың воркерлерін масштабтау.

Хаос-жаттығулар: JP аймағының құлауы, офлайн әмиян, уақыттың синхрондалмауы; outbox және деградацияларды тексеру (pause triggers/no new contributions).

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

Студия/RGS үшін

Теңшелетін 'contribution' және дұрыс 'round _ id '/' bet _ id'.
Транзакцияларды «айналып өту» жарияланымдары жоқ (тек outbox/CDC).
Дубль/қайталанған триггер/өтемақы тестілері.
max bet/біліктілік лимиттері JP-ге беріледі.

Оператор/платформа үшін

Ledger - ақиқаттың көзі, 'wallet. credit 'дедуппен.
RG/AML-табандары төлемде өңделеді; SAR/STR есептері.
Дашбордтар p95 'trigger → credit', error rate, пулдарды салыстыру.

JP иесі үшін

WORM-аудит формулалар/seed/лимиттер өзгерістері.
Registry және versioning оқиғаларының схемалары.
DR: RPO ≤ 5 мин, RTO ≤ 30 мин; тұрақты оқу-жаттығулар.
RLS/брендтер/лицензиялар бойынша оқшаулау; per region кілттері/құпиялары.

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

Пулдар мен төлемдердің өлшемдерін ДБ-да қолмен түзету.

Кредиттер үлесінің болмауы.

Телеметрияны outbox/CDC → «жоғалған» жарналарсыз/триггерсіз жариялау.

Әр түрлі өңірлердің PII және ақша деректерін араластыру.

Жаңа сертификаттаусыз RTP базалық ойынына әсер ететін джекпот.

Әмиян мен пулды салыстыру жоқ; есептер OLTP жауынгерлік бойынша құрылады.

Джекпот-жүйелердің API - бұл студия, платформа және оператор арасындағы ақшалай-оқиғалық келісімшарт. Оның іргетасы: идемпотенттілік және сағалар, қатаң ақша оқшаулау, нақты оқиғалар схемалары, қауіпсіздік және WORM-аудит, бақылау және SLO. Мұндай дизайнда фикс/прогрессивті және желілік пулдар болжамды түрде кеңейтіледі, төлемдер дұрыс, ал реттеуші және бизнес-есептілік ашық және сенімді болып қалады.