Mines — tài liệu ghép client

Chọn ô trên lưới, tránh mìn. Cashout hoặc clear board để nhận thưởng. Client nói HTTP JSON với server game. Trang này chỉ được serve khi ENVIRONMENT != production.

1. Tổng quan

2. Demo bàn 5×5

Số trên ô = position. Xanh = gem đã mở, đỏ = mìn lộ, xám = chưa mở.

Ví dụ: ô hàng 3 cột 3 → 3 * 5 + 3 = 18 (mìn). Client highlight theo opened_positions / mine_positions, không tự random mìn.

3. Auth & envelope

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

Mọi API dưới /api/v1 cần JWT. Trang docs không cần token. HTTP 200 + code = 0 là thành công; payload nằm trong msg.

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

4. GET /api/v1/gameplay

Gọi 1 lần khi vào. Set session. Thiếu bước này thì action sau trả code 69.

Level

{
  "code": 0,
  "msg": {
    "user_money": 500000,
    "bet": 1000,
    "bets": [200, 1000, 2000, 10000],
    "show_bets": [200, 1000, 2000, 10000],
    "levels": [
      {"row_size": 5, "col_size": 5, "mines": [{"number_of_mines": 3, "init_multiplier": 1.12}], "quick_mines": [1, 3, 5]}
    ],
    "is_playing": true,
    "opened_positions": [0, 3, 6, 12],
    "number_of_mines": 3,
    "current_multiplier": 1.48,
    "next_multiplier": 1.72,
    "current_row_size": 5,
    "current_col_size": 5,
    "multipliers": [1.12, 1.28, 1.48, 1.72]
  }
}

5. POST /api/v1/start

Debit bet ngay. Không gọi khi is_playing.

POST /api/v1/start
{ "bet": 1000, "row_size": 5, "col_size": 5, "number_of_mines": 3 }

{
  "code": 0,
  "msg": {
    "user_money": 499000,
    "bet": 1000,
    "number_of_mines": 3,
    "current_multiplier": 0,
    "next_multiplier": 1.12,
    "multipliers": [1.12, 1.28, 1.48, 1.72],
    "col_size": 5,
    "row_size": 5
  }
}

6. POST /api/v1/open

POST /api/v1/open
{ "position": 6 }

{
  "code": 0,
  "msg": {
    "position": 6,
    "multiplier": 1.28,
    "next_multiplier": 1.48,
    "is_stopped": false,
    "is_mine": false,
    "user_money": 499000
  }
}

{
  "code": 0,
  "msg": {
    "position": 18,
    "is_stopped": true,
    "is_mine": true,
    "mine_positions": [8, 18, 22],
    "user_money": 499000
  }
}

7. POST /api/v1/stop

Cashout. Cần đã mở ≥ 1 gem. Credit round(current_multiplier × bet) reason WIN STOP. Lộ mine_positions.

POST /api/v1/stop

{
  "code": 0,
  "msg": {
    "win_amount": 1480,
    "user_money": 500480,
    "mine_positions": [8, 18, 22]
  }
}

8. GET /top-win · GET /history

GET /api/v1/top-win
{ "code": 0, "msg": { "winners": [{ "rank": 1, "user_id": 1001, "username": "alice", "total_win": 880000 }] } }

GET /api/v1/history
{ "code": 0, "msg": { "logs": [{ "user_money": 500480, "win_amount": 1480, "bet": 1000, "multiplier": 1.48, "row_size": 5, "col_size": 5, "created_at": 1720000000 }] } }

9. Luồng ghép

1. Mở game → GET /gameplay. Render levels, bets, money. Nếu is_playing: vẽ gem theo opened_positions, enable Stop.
2. User chọn bet + size + số mìn → POST /start. Cập nhật user_money, vẽ lưới trống, hiện next_multiplier.
3. Tap ô → POST /open {position}. Gem: highlight, cập nhật multiplier. Mine: lộ mine_positions, kết thúc, win = 0.
4. Stop bất kỳ lúc đã có gem, hoặc đợi clear hết ô an toàn (server tự credit).
5. Luôn lấy chip từ user_money của response vừa nhận.

10. Error & tiền

11. Checklist client

• Vào game: GET /gameplay trước mọi start/open.
• Index = row * col_size + col. Hiện số index lúc debug.
• Bet chỉ gửi giá trị trong bets; size/mines chỉ từ levels.
• Không /start khi is_playing; restore thay vì ván mới.
• Nổ mìn: không cộng chip. Clear / stop: tin win_amount.
• Cheat cheat_mine_positions chỉ non-prod.
• Không gọi song song 2 open — đợi response + animation.