KioskGaming Backend — Báo cáo kỹ thuật (2026-06-24)

Tổng quan nghiệp vụ

kioskgaming_backend là composition root cho toàn bộ nền tảng — 6 frontend apps (kiosk player, admin, agent, super agent, shop, cashier) và kiosk heartbeat gọi vào REST API trên port 3001. Codebase hiện tại trên nhánh dev dùng kiến trúc phân lớp routes → controllers → biz → core → infra → repositories → PostgreSQL, khởi tạo qua src/bootstrap/.

🔐

Xác thực đa portal

JWT cho player (JWT_SECRET), admin OTP 2FA (ADMIN_JWT_SECRET), agent/shop/super-agent/cashier portal auth + shared /api/portal-auth (forgot password, login 2FA).

💰

Thanh toán online

4 gateway: LinkMePay, 0xProcessing, BTCPay, Meld — deposit/withdrawal adapter registry, webhook verify, idempotency qua CallbackLog.

🎮

22 Game providers

Adapter registry trong gameProviderAdapters/ — credit/debit/sync balance, GameProviderApiLog audit, retry queue + masterWorker reconciliation.

🏪

B2B hierarchy

Super Agent → Agent → Shop → Player; Cashier module riêng cho quầy tiền mặt; USD wallet + credit ledger cho từng cấp portal.

📨

Async messaging

RabbitMQ workers (email, SMS, Telegram, low-balance check) + masterWorker tick 60s (retry, timeout, payout poll, agent balance sync).

🛡️

Architecture lint

npm run architecture:check ngăn vi phạm layering (controller → repository trực tiếp, biz import sai tầng). CI: lint + architecture + jest.

Kiến trúc phân lớp

Mọi request đi qua bootstrap composition root — không còn mount route trực tiếp trong server.js.

HTTP Request → helmet · cors · rateLimit · language · domainMiddleware

↓

routes/ — URL + middleware + controller

↓

controllers/ — parse input, gọi biz service

↓

services/biz/ — orchestration, validation nghiệp vụ (58 files)

↓

services/core/ — domain CRUD qua repository (48 files)

↓

services/infra/ — email, telegram, wallet, fraud, sync (58 files)

↓

repositories/ (45) → PostgreSQL · Redis cache/lock · RabbitMQ

src/bootstrap/index.js — buildAppWithRoutes()

initDatabase() → createRepositories(db) → initServices(db, repos)
→ buildApp() → mountRoutes(app, …) → startWorkers(db)

Payment providers

Deposit adapters: getDepositAdapter() trong services/payment/depositAdapters/. Withdrawal adapters: getWithdrawalAdapter() trong withdrawalAdapters/. Webhook routes mount tại /api/payment/*.

Provider	Loại	Khả năng	Webhook / Worker
LinkMePay `linkmepay`	Fiat link / eCash	Deposit, Withdrawal	IPN + payout IPN webhooks
0xProcessing `zeroxprocessing`	Crypto multi-coin	Deposit, Withdrawal	Webhook + static wallet + payout poll worker
BTCPay Server `btcpay`	Bitcoin / Lightning	Deposit, Withdrawal	Webhook + payout poll worker
Meld `meld`	Fiat on-ramp	Deposit only	Webhook on-ramp completion

Luồng deposit (tóm tắt)

POST /api/payment/deposit

depositService tạo PaymentTransaction pending, gọi deposit adapter → trả paymentUrl/address.

Provider webhook

depositCallbackService verify signature, ghi CallbackLog, idempotency check, credit wallet trong DB transaction.

Notify + retry

Telegram/email qua RabbitMQ; lỗi tạm thời → retryQueue + masterWorker retry task.

Game providers (21 adapters)

Registry: src/services/gameProviderAdapters/index.js — mỗi adapter extend baseProvider.js, map alias (firekirin→fkterminal, juwa→gamevault…).

BlueDragon

bluedragon

REST sweepstakes API

Cashier

cashier

Vegas X / in-person terminal

Vegas7Games

vegas7games

Vegas X API variant

FKTerminal

fkterminal

alias: firekirin

PMTerminal

pmterminal

alias: pandamaster

MWTerminal

mwterminal

alias: milkyway

OSTerminal

osterminal

alias: orion

GameVault

gamevault

alias: juwa

Jack2Win

jack2win

vblink777, egame99, ultrapanda…

OpenJack2Win

openjack2win

Open API jack2.win

LasVegasSweeps

lasvegassweeps

Sweepstakes

River Pay

riverpay

River payment terminal

CashFrenzy

cashfrenzy

Terminal API

GameRoom

gameroom

Game room terminal

MrAllInOne

mrallinone

Multi-game terminal

VegasRoll

vegasroll

Roll games

Mafia77777

mafia77777

Slot terminal

MegaSpin

megaspin

MegaSpin Pay terminal

Galaxy World

galaxyworld

Galaxy terminal

Glamor Spin

glamorspin

FastAPI provider

Noble777

noble777

Noble777 terminal

B2B portal APIs

Portal	Auth prefix	API prefix	Chức năng chính
Agent	`/api/agent-auth`	`/api/agent`	Dashboard, shops/players, credit purchase/distribute, USD withdrawals + OTP, cash settlement, ZeroX static wallets, broadcasts
Super Agent	`/api/super-agent-auth`	`/api/super-agent`	Quản lý agents, credit distribution, USD ledger, portal withdrawal limits, hierarchy stats
Shop	`/api/shop-auth`	`/api/shop`	Kiosk subdomain, player transfer/deposit, credit purchase, fraud indicators, cash transactions, provider fees
Cashier	`/api/cashier-auth`	`/api/cashier`	Shift management, cash in/out, device access, redemption approval (`modules/cashier-management/`)
Shared portal	`/api/portal-auth`	—	Forgot password, login 2FA (`portalLogin2faService`), credential notify emails
Admin	`/api/admin-auth`	`/api/admin/*`	RBAC 4 roles, payment approval, CDN agents/shops/players, finance corrections, monitoring

Biến môi trường quan trọng

.env — nhóm biến thường dùng (xem .env.example đầy đủ)

# Core
PORT=3001 NODE_ENV DB_HOST/DB_PORT/DB_NAME/DB_USER/DB_PASS
JWT_SECRET ADMIN_JWT_SECRET SUPER_ADMIN_JWT_SECRET
REDIS_URL RABBITMQ_URL RABBITMQ_ENABLED

# Payment
ZEROX_PROCESSING_* BTCPAYSERVER_* LinkMePay credentials MELD_*

# Portal URLs
AGENT_SITE_URL SUPERAGENT_SITE_URL SHOP_SITE_URL CASHIER_SITE_URL ADMIN_SITE_URL

# Security / ops
REQUEST_SIGNING_SECRET TELEGRAM_BOT_TOKEN CF_API_TOKEN (Cloudflare DNS)
MASTER_WORKER_INTERVAL_MS=60000 ZEROX_PAYOUT_POLL_ENABLED BTCPAY_PAYOUT_POLL_ENABLED

Chi tiết bootstrap, workers, cookbook → 01-backend-detail.html

Route map (tóm tắt)

Prefix	Mô tả	Auth
`/api/auth`, `/api/users`, `/api/wallet`	Player kiosk	JWT_SECRET
`/api/payment`	Deposit/withdraw + webhooks	JWT / signature
`/api/game-wallet`, `/api/game-providers`	Game wallet sync	JWT
`/api/kiosk/*`	Heartbeat, info, win ticker	Request signing
`/api/admin/*`	Platform admin	ADMIN_JWT + RBAC
`/api/agent`, `/api/shop`, …	B2B portals	Portal JWT + session
`/health`	Health check	Public