Đặc tả: Prize Allocation Feature

Module: application-core (producers) + batch (JMS consumers) Status: Production

1. Tổng quan

Prize Allocation là trung tâm phân phối tài nguyên của hệ thống. Mọi action tạo phòng, ghép trận, mở gacha, present box, mission reward đều phải đi qua queue topology này để đảm bảo serial processing và tránh race condition inventory.

2. Queue topology

Queue	Listener class	Concurrency	Use case
`queue-prize-allocation-PRIZE`	`JMSPrizeAllocationListener`	`1-1`	PVP/PVE có stock hữu hạn
`queue-prize-allocation-PRIZE_FOR_STREAMER`	`JMSPrizeForStreamerAllocationListener`	`1-1`	Streaming mode prizes
`queue-prize-allocation-UNLIMITED`	`JMSUnlimitedPrizeAllocationListener`	`20-100`	Free play, treasure box (unlimited stock)
`queue-prize-allocation-MISSION`	`JMSMissionAllocationListener`	configurable	Mission rewards
`queue-prize-allocation-GACHA`	`JMSGachaAllocationListener`	configurable	Gacha pulls
`queue-prize-allocation-PRESENT_BOX`	`JMSPresentBoxAllocationListener`	configurable	Present box opens
`queue-prize-allocation-MKP`	`JMSMKPAllocationListener`	configurable	Marketplace
`queue-prize-allocation-PRESALE`	`JMSPresaleAllocationListener`	configurable	Presale orders
`queue-prize-allocation-NONE`	`JMSNoneAllocationListener`	configurable	No-allocation actions

3. Functional requirements

ID	Requirement	Chi tiết
PA-F-01	Message contract	Mọi message phải có `allocationType` + `actionType`
PA-F-02	Type guard	Listener validate `allocationType` match với queue của nó trước khi xử lý
PA-F-03	Single prize	`prizeId` (string) cho các action cũ
PA-F-04	Multi-match prize	`prizeIds` (List) cho PVP_MULTI_MATCH
PA-F-05	Rollback support	`actionType=DECREASE` kèm `PrizeRollbackData` để rollback inventory
PA-F-06	Mint allocation	`actionType=MINT_ALLOCATION` tạo allocation records cho Hunter/Gauntlet/BountyBall
PA-F-07	Idempotency	Listener phải tránh double-processing khi redelivery

4. Action types

ActionType	Mô tả
`CREATE_PVE_FREE_PLAY`	Tạo PVE Free Play room
`CREATE_PVE_SINGLE_PLAY`	Tạo PVE Single Play room
`JOIN_PVE_FREE_PLAY`	Join PVE Free Play
`JOIN_PVE_SINGLE_PLAY`	Join PVE Single Play
`JOIN_AUTO_MATCH_MATCHING`	Vào hàng chờ ghép trận
`JOIN_OPPONENT_POOL`	Vào pool đối thủ
`LEAVE_AUTO_MATCH_MATCHING`	Rời hàng chờ
`LEAVE_OPPONENT_POOL`	Rời pool đối thủ
`DECREASE`	Rollback/deduct tài nguyên
`MINT_ALLOCATION`	Tạo NFT allocation records

5. Allocation type routing rules

Điều kiện	AllocationType
`PVE_FREE_PLAY` action	`UNLIMITED`
`prize.reservedType == STREAMING`	`PRIZE_FOR_STREAMER`
`prize.prizeType == TREASURE_BOX` (non-streaming)	`UNLIMITED`
`prize.prizeType == INVITATION_CARD` (non-streaming)	`UNLIMITED`
Mission rewards	`MISSION`
Gacha pulls	`GACHA`
Present box	`PRESENT_BOX`
Marketplace	`MKP`
Presale	`PRESALE`
Default PVP/PVE prize	`PRIZE`

6. PrizeAllocationData structure

public class PrizeAllocationData {
    PrizeEnum.AllocationType allocationType;  // queue routing key
    CreateRoomActionType actionType;           // business action
    CreateRoomData createRoomData;             // room creation context
    PrizeRollbackData prizeRollback;           // rollback info (for DECREASE)
    MintAllocationData mintAllocation;         // NFT mint info
    List<String> prizeIds;                     // multi-match support
}

7. Acceptance criteria

[ ] CREATE_PVE_FREE_PLAY → route tới UNLIMITED queue, listener xử lý đúng
[ ] CREATE_PVE_SINGLE_PLAY với streaming prize → route PRIZE_FOR_STREAMER, concurrency 1-1
[ ] DECREASE action với PrizeRollbackData → rollback inventory/allocation đúng
[ ] MINT_ALLOCATION với Hunter/Gauntlet/BountyBall → tạo đúng số allocation records
[ ] Listener từ chối message có sai allocationType
[ ] Multi-match prizeIds → tất cả prizes được process
[ ] Queue PRIZE không process concurrent (concurrency 1-1)
[ ] Queue UNLIMITED xử lý concurrent (concurrency 20-100)

8. Constraints

Queue PRIZE và PRIZE_FOR_STREAMER dùng concurrency=1-1 để serialise processing.
Queue UNLIMITED dùng concurrency=20-100 cho throughput cao.
Listener dùng @JmsListener với container factory jmsListenerContainerFactory.
Message format: JSON string của PrizeAllocationData.

9. Code references

application-core/
  service/prize_allocation/
    PrizeAllocationData.java          # Message DTO
    SendPrizeAllocationMessageService.java  # Producer
    PrizeAllocationHelperService.java # Allocation type routing logic
    MintAllocationData.java
    PrizeRollbackData.java

batch/
  jms/prize_allocation/
    JMSPrizeAllocationListener.java           # PRIZE queue
    JMSPrizeForStreamerAllocationListener.java # PRIZE_FOR_STREAMER queue
    JMSUnlimitedPrizeAllocationListener.java  # UNLIMITED queue
    JMSMissionAllocationListener.java
    JMSGachaAllocationListener.java
    JMSPresentBoxAllocationListener.java
    JMSMKPAllocationListener.java
    JMSPresaleAllocationListener.java
    JMSNoneAllocationListener.java
  jms/service/
    CreateRoomJMSService.java                 # JMS-side room creation