Mini Poker — tài liệu ghép client

Video poker 5 lá. Server chia bài, trả combination_type (int hạng bài) + multiplier. Jackpot khi sảnh thông có Át. Credit ngay mỗi spin. Trang này chỉ được serve khi ENVIRONMENT != production.

1. Tổng quan

2. Luồng ghép

1. Vào game → GET /gameplay (+ GET /jackpots cho meter). Vẽ 5 lá init_cards.
2. User chọn bet ∈ bets.
3. POST /spins. Lật 5 lá cards, hiện hạng từ combination_type + multiplier.
4. is_jackpot → fanfare, cộng jackpot_win_amount. Cập nhật meter = jackpot.
5. Chip = user_money. History / top-win cho panel phụ.

3. Auth & envelope

Authorization: Bearer <access_token>
Content-Type: application/json

JWT bắt buộc dưới /api/v1. HTTP 200 + code = 0; payload trong msg.

{ "code": 0, "msg": { ... } }

4. Bài, id & combination_type

Ví dụ Full House (3 K♥ + 2 A♠) — combination_type do server trả, client map label.

card_id = rank * 4 + suit. Suit: 0 ♠ · 1 ♣ · 2 ♦ · 3 ♥. Rank: 0 = 2 … 8 = 10 · 9 = J · 10 = Q · 11 = K · 12 = A. Ví dụ A♥ = 51, K♠ = 44, 2♠ = 0.

combination_type là int từ server (hạng bài). Map tham chiếu (iota server); luôn tin giá trị response, đừng tự chấm lại trừ khi debug:

5. GET /api/v1/gameplay

GET /api/v1/gameplay

{
  "code": 0,
  "msg": {
    "init_cards": [0, 6, 12, 18, 24],
    "bets": [100, 500, 1000, 5000],
    "show_bets": [100, 500, 1000, 5000],
    "bet": 1000
  }
}

6. POST /api/v1/spins

POST /api/v1/spins
{ "bet": 1000 }

Full house

{
  "code": 0,
  "msg": {
    "user_money": 549000, "win_amount": 50000, "bet": 1000,
    "cards": [44, 45, 47, 48, 51],
    "combination_type": 5, "multiplier": 50,
    "is_jackpot": false, "jackpot_win_amount": 0, "jackpot": 880000
  }
}

Jackpot (A-high straight flush)

{
  "code": 0,
  "msg": {
    "user_money": 2500000, "win_amount": 2000000, "bet": 1000,
    "cards": [35, 39, 43, 47, 51],
    "combination_type": 7, "multiplier": 0,
    "is_jackpot": true, "jackpot_win_amount": 2000000, "jackpot": 5000
  }
}

Không ăn

{
  "code": 0,
  "msg": {
    "user_money": 499000, "win_amount": 0, "bet": 1000,
    "cards": [0, 6, 12, 18, 25],
    "combination_type": 8, "multiplier": 0,
    "is_jackpot": false, "jackpot_win_amount": 0, "jackpot": 880000
  }
}

7. GET /api/v1/jackpots

GET /api/v1/jackpots

{ "code": 0, "msg": { "jackpots": [{ "bet": 100, "jackpot_amount": 88000 }, { "bet": 1000, "jackpot_amount": 880000 }] } }

8. GET /api/v1/jackpots-history

GET /api/v1/jackpots-history

{
  "code": 0,
  "msg": {
    "jackpots": [
      { "time": 1710000200, "user_id": 2001, "username": "ace", "bet": 1000, "win_amount": 2000000, "cards": [35,39,43,47,51] }
    ]
  }
}

9. GET /api/v1/top-win

GET /api/v1/top-win

{ "code": 0, "msg": { "winners": [{ "rank": 1, "user_id": 2001, "username": "ace", "total_win": 1990000 }] } }

10. GET /api/v1/spins-history

GET /api/v1/spins-history

{
  "code": 0,
  "msg": {
    "spins": [{
      "user_money": 549000, "win_amount": 50000, "bet": 1000, "cards": [44,45,47,48,51],
      "combination_type": 5, "multiplier": 50, "is_jackpot": false,
      "jackpot_win_amount": 0, "jackpot": 880000, "created_at": 1710000300
    }]
  }
}

11. Animation

1. Lock Deal tới khi có response.
2. Lật 5 lá theo cards (decode id → rank/suit; đỏ nếu ♦/♥).
3. Hiện badge hạng theo combination_type + số multiplier.
4. JP: bỏ qua anim nhân, hiện boom jackpot_win_amount, cập nhật meter jackpot.

12. Cheat (chỉ non-prod / cheater)

reels = 5 cột, mỗi cột 1 card id (handler flatten):

{ "bet": 1000, "reels": [[35], [39], [43], [47], [51]] }

Production bỏ qua. 5 id phải hợp lệ 0–51.

13. Error & tiền

14. Checklist client

• GET /gameplay khi vào. Decode card id = rank×4+suit.
• Hiện hạng từ combination_type (int server) + multiplier.
• JP khi is_jackpot; meter từ /jackpots và field jackpot.
• Không song song 2 spin / user.