Đặc tả: Game & Room Management Feature

Module: websocket (port 8081) + web (port 8080) Status: Production

1. Tổng quan

Feature này quản lý vòng đời game room cho các mode PVE Free Play và PVE Single Play. Commands đến qua WebSocket, được routing qua RoomCmdConsumer → CreateRoomService → Prize Allocation Queue → JMS Listener → CreateRoomJMSService.

2. Phạm vi

In-scope WebSocket commands (`@OnCmd`)

Command	Handler	Mô tả
`CREATE_PVE_FREE_PLAY_ROOM`	`RoomCmdConsumer`	Tạo PVE Free Play room
`JOIN_PVE_FREE_PLAY_ROOM`	`RoomCmdConsumer`	Join PVE Free Play room
`CREATE_PVE_SINGLE_PLAY_ROOM`	`RoomCmdConsumer`	Tạo PVE Single Play room
`JOIN_PVE_SINGLE_PLAY_ROOM`	`RoomCmdConsumer`	Join PVE Single Play room
`READY_FOR_START_GAME`	`RoomCmdConsumer`	Báo sẵn sàng
`QUIT_GAME`	`RoomCmdConsumer`	Thoát game/room
`RECHARGE_GAME`	`RoomCmdConsumer`	Nạp lại tài nguyên
`CANCEL_GAME`	`RoomCmdConsumer`	Hủy game

In-scope REST APIs (`web` module)

Endpoint	Method	Mô tả
`/api/game/*`	GET/POST	Query game state, machine info
`/api/room/*`	GET/POST	Room info, start/end game signal

Out-of-scope

Mục	Lý do
PVP matching logic	Thuộc feature-matching-matchmaking
Prize calculation	Thuộc feature-prize-allocation
Payment in game	Thuộc feature-payment-marketplace

3. User stories

ID	Role	Story	Acceptance
ROOM-US-01	Player	Tạo PVE Free Play room → vào ngay không cần đối thủ	Room tạo thành công, broadcast `ROOM_CREATED`
ROOM-US-02	Player	Tạo PVE Single Play với prizeId cụ thể → hệ thống check balance + tạo room	Room tạo hoặc nhận reason code
ROOM-US-03	Player	Join room của người khác → vào chơi	`ROOM_JOIN_SUCCESS` event
ROOM-US-04	Player	Ready → game bắt đầu khi đủ người ready	`GAME_START` broadcast
ROOM-US-05	Player	Quit giữa chừng → room cleanup + rollback resource	Resource được rollback
ROOM-US-06	Player	Fake machine mode → bỏ qua IoT device check	Hoạt động trong dev/test

4. Functional requirements

ID	Requirement	Chi tiết
ROOM-F-01	Validation	`CreateRoomValidationService` validate trước khi route queue
ROOM-F-02	Queue routing	PVE Free Play → `UNLIMITED` queue; PVE Single Play → theo `prizeType`/`reservedType`
ROOM-F-03	Fake machine support	`skipLifeGauge` + `fakeMachine` flags để test
ROOM-F-04	Room state in Redis	Room state lưu trong `RRoomModel` via `RRoomService`
ROOM-F-05	Broadcast events	Kết quả tạo/join room broadcast qua `BroadcastPubSubService`
ROOM-F-06	Machine view cleanup	Khi bắt đầu chơi → `SendMachineViewMessageService` xóa live view
ROOM-F-07	Dynamic queue per machine	`ProgrammaticEndpointRegistration` tạo queue riêng per `machineId` khi startup

5. Business rules

PVE Free Play allocation type: UNLIMITED (không giới hạn stock).
PVE Single Play allocation type: dựa theo reservedType của prize:
STREAMING → PRIZE_FOR_STREAMER
TREASURE_BOX / INVITATION_CARD (non-streaming) → UNLIMITED
Default → PRIZE
Validation lỗi trả về event VALIDATE_GAME + reason field qua WebSocket.
Machine view (MachineViewCmdConsumer) bị xóa khi player start game.

6. Data contracts

WebSocket command payload - `CREATE_PVE_SINGLE_PLAY_ROOM`

{
  "cmd": "CREATE_PVE_SINGLE_PLAY_ROOM",
  "queue_data": {
    "playable_game_booth_setting_id": "<id>",
    "prize_id": "<prizeId>",
    "machine_id": "<machineId>",
    "skip_life_gauge": false,
    "fake_machine": false
  }
}

WebSocket event response - validation fail

{
  "event_type": "VALIDATE_GAME",
  "reason": "INVALID_PRIZE_ID | INSUFFICIENT_BALANCE | ROOM_ALREADY_EXIST | ..."
}

REST - `POST /api/room/start-game`

{
  "room_id": "<roomId>",
  "machine_id": "<machineId>"
}

7. Acceptance criteria

[ ] CREATE_PVE_FREE_PLAY_ROOM tạo room thành công → client nhận broadcast
[ ] CREATE_PVE_SINGLE_PLAY_ROOM với prize không đủ balance → VALIDATE_GAME với reason cụ thể
[ ] READY_FOR_START_GAME khi đủ người → GAME_START broadcast
[ ] QUIT_GAME → room state cleanup, resource rollback qua queue
[ ] CREATE_PVE_FREE_PLAY_ROOM luôn route tới UNLIMITED queue
[ ] CREATE_PVE_SINGLE_PLAY_ROOM với streaming prize → PRIZE_FOR_STREAMER queue
[ ] Concurrent room creation cùng user → chặn duplicate
[ ] Dynamic queue per machine được tạo đúng lúc startup

8. Constraints

Room state lưu trong Redis (in-memory, không persist qua restart).
Command processing là synchronous per user connection.
Fake machine mode chỉ cho phép trong non-production profiles.

9. Code references

websocket/
  handler/consumer_handler/
    RoomCmdConsumer.java          # @OnCmd handlers cho room commands
    GameOperationCmdConsumer.java # Game operation commands
  handler/handle/
    CreateRoomService.java        # Core routing + validation

batch/
  jms/
    service/CreateRoomJMSService.java        # JMS processing
    register_destination/
      ProgrammaticEndpointRegistration.java  # Dynamic queue registration
      GameModeCreateRoomJMSListener.java     # Per-machine listener
      CreateMachineStartRoomJMSListener.java

web/
  controllers/game/GameController.java
  controllers/room/RoomController.java

application-core/
  service/cache_room/
    create_room/CreateRoomData.java
    create_room/validate/CreateRoomValidationService.java
    RRoomService.java