Как работает 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, кап, число участников, 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, распределение)

Контракты: Avro/JSON Schema + Schema Registry, ключи партиционирования `tenant_id`, `pool_id`, `player_id`. Версионирование — backward-compatible.

6) Алгоритмы триггера (высокоуровнево)

Вероятностный (p-устойчивый): на каждый квалифицированный раунд генерируем hit с вероятностью `p` (зависящей от пула/типа уровня).

Диапазонный (must-drop): пул обязан упасть до cap-суммы или дедлайна — держим внутренний random в диапазоне [min,max], публикуем cap/ETA.

Сид- и 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 + подписи (HMAC/EdDSA) на всех S2S-вызовах; короткоживущие токены.

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. На таком дизайне фикс/прогрессивные и сетевые пулы масштабируются предсказуемо, выплаты остаются корректными, а регуляторная и бизнес-отчётность — прозрачной и достоверной.