Đặc tả: Admin Backoffice Feature
Module: admin (port 8083)
Auth: Email/password login → JWT (riêng với user JWT)
Status: Production
1. Tổng quan
Module admin là backoffice portal cho operators/admin team để quản lý toàn bộ hệ thống BountyHunter: máy vật lý (crane machine), users, NFTs, events, prizes, livestream, IoT, và xem dashboard KPIs.
2. Nhóm chức năng
2.1 Authentication & Authorization
| Controller |
Endpoint prefix |
Mô tả |
AuthController |
/api/admin/auth |
Email login, JWT issue cho admin |
AdminController |
/api/admin/admins |
CRUD admin accounts, đổi role/status |
RoleController |
/api/admin/roles |
Quản lý roles |
RuleController |
/api/admin/rules |
Quản lý rules/permissions |
2.2 Machine Management (IoT)
| Controller |
Endpoint prefix |
Mô tả |
MachineController |
/api/admin/machines |
CRUD crane machines, change state/game mode/group |
CraneMachineController |
/api/admin/crane-machines |
Crane-specific: direction, chromakey, boothId |
MachineGroupController |
/api/admin/machine-groups |
Nhóm machines |
MachineHistoryLogController |
/api/admin/machine-history-logs |
Xem lịch sử log machine |
MachineUsageLimitController |
/api/admin/machine-usage-limits |
Usage limits per machine |
MachineUsageRateController |
/api/admin/machine-usage-rates |
Usage rate statistics |
MachineContactController |
/api/admin/machine-contacts |
Quản lý contact/support tickets cho machine |
MachineContactCategoriesController |
/api/admin/machine-contact-categories |
Categories cho machine contacts |
IotDeviceController |
/api/admin/iot-devices |
IoT device management |
IotAccountController |
/api/admin/iot-accounts |
IoT account credentials |
CameraController |
/api/admin/cameras |
Camera status check |
SrsControlClusterController |
/api/admin/srs-control-clusters |
SRS streaming cluster management |
2.3 User Management
| Controller |
Endpoint prefix |
Mô tả |
UserController |
/api/admin/users |
Search/view/ban users, send resources, reset |
UserSystemCoinController |
/api/admin/user-system-coins |
Adjust user coin balance |
UserSystemTicketController |
/api/admin/user-system-tickets |
Manage user tickets |
UserKOLController |
/api/admin/user-kols |
KOL user management |
UserPresentBoxController |
/api/admin/user-present-boxes |
User present box management |
UserPaymentHistoryController |
/api/admin/user-payment-histories |
Payment history lookup |
UserMissionProgressController |
/api/admin/user-mission-progress |
Mission progress, batch triggers |
UserGachaHistoryController |
/api/admin/user-gacha-histories |
Gacha history |
UserAttributePointHistory |
/api/admin/user-attribute-point-histories |
Attribute point history |
ReferralController |
/api/admin/referrals |
Referral management |
2.4 NFT Management
| Controller |
Endpoint prefix |
Mô tả |
NftHunterController |
/api/admin/nft-hunters |
Hunter NFT CRUD, mint |
NftGauntletController |
/api/admin/nft-gauntlets |
Gauntlet NFT CRUD, mint |
NftBountyBallController |
/api/admin/nft-bounty-balls |
Bounty Ball NFT CRUD, mint |
NftGenesisController |
/api/admin/nft-genesis |
Genesis NFT management |
NftGenesisPackageController |
/api/admin/nft-genesis-packages |
Genesis packages |
NftMetadataController |
/api/admin/nft-metadata |
NFT metadata management |
NftContractController |
/api/admin/nft-contracts |
NFT contract management |
NftGachaItemController |
/api/admin/nft-gacha-items |
NFT gacha item config |
NftPrizeController |
/api/admin/nft-prizes |
NFT prize management |
NftHolderController |
/api/admin/nft-holders |
NFT holder tracking |
NftHolderRevenueMonthlyController |
/api/admin/nft-holder-revenue-monthly |
Monthly revenue per holder |
BountyBallUsageHistoryController |
/api/admin/bounty-ball-usage-histories |
Bounty ball usage log |
MasterHunterController |
/api/admin/master-hunters |
Hunter master data |
MasterGauntletController |
/api/admin/master-gauntlets |
Gauntlet master data |
MasterBountyBallController |
/api/admin/master-bounty-balls |
Bounty Ball master data |
HunterArParamController |
/api/admin/hunter-ar-params |
Hunter AR parameters |
FusionAwakenConfigController |
/api/admin/fusion-awaken-configs |
Hunter fusion/awaken config |
2.5 Event & Leaderboard
| Controller |
Endpoint prefix |
Mô tả |
EventController |
/api/admin/events |
CRUD events (Standard, Tournament, SkillRank, Translation) |
UserEventWhitelistController |
/api/admin/user-event-whitelists |
Event whitelist |
StandardLeaderboardController |
/api/admin/standard-leaderboards |
Standard event leaderboard |
TournamentLeaderboardController |
/api/admin/tournament-leaderboards |
Tournament leaderboard |
LivestreamLeaderboardController |
/api/admin/livestream-leaderboards |
Livestream leaderboard |
TreasureLeaderboardController |
/api/admin/treasure-leaderboards |
Treasure box leaderboard |
LevelLeaderboardController |
/api/admin/level-leaderboards |
Level leaderboard |
SkillRankLeaderboardController |
/api/admin/skill-rank-leaderboards |
Skill rank leaderboard |
2.6 Prize & Reward
| Controller |
Endpoint prefix |
Mô tả |
PrizeController |
/api/admin/prizes |
CRUD prizes |
PrizeStreamingController |
/api/admin/prize-streamings |
Streaming prizes |
CategoryPrizeController |
/api/admin/category-prizes |
Prize categories |
RewardController |
/api/admin/rewards |
Rewards management |
RewardContainerController |
/api/admin/reward-containers |
Reward containers |
TreasureBoxController |
/api/admin/treasure-boxes |
Treasure box config |
TreasureBoxBonusController |
/api/admin/treasure-box-bonuses |
Treasure box bonuses |
TreasureBoxUpRankParamController |
/api/admin/treasure-box-up-rank-params |
Up-rank parameters |
DailyRewardPoolConfigController |
/api/admin/daily-reward-pool-configs |
Daily reward pool |
PresentBoxController |
/api/admin/present-boxes |
Present box CRUD |
ApRewardController |
/api/admin/ap-rewards |
AP (Attribute Point) rewards |
2.7 Gacha & Shop
| Controller |
Endpoint prefix |
Mô tả |
GachaController |
/api/admin/gachas |
Gacha config |
WishOrbSettingsController |
/api/admin/wish-orb-settings |
Wish Orb rarity config |
ShopPackageController |
/api/admin/shop-packages |
Shop packages |
PromotionPackageController |
/api/admin/promotion-packages |
Promotion packages |
BonusPassPurchaseSettingController |
/api/admin/bonus-pass-purchase-settings |
Bonus pass config |
ArItemController |
/api/admin/ar-items |
AR items |
MasterArItemController |
/api/admin/master-ar-items |
AR item master data |
NonNftItemController |
/api/admin/non-nft-items |
Non-NFT items |
2.8 Livestream Management
| Controller |
Endpoint prefix |
Mô tả |
LivestreamController |
/api/admin/livestreams |
Xem/manage livestream sessions |
LivestreamBanController |
/api/admin/livestream-bans |
Ban users từ livestream |
StreamerController |
/api/admin/streamers |
Streamer accounts |
StreamerPrizeAllocationController |
/api/admin/streamer-prize-allocations |
Prize config cho streamers |
LivestreamSyncHistoryController |
/api/admin/livestream-sync-histories |
Room sync history |
LivestreamGiftHistoryController |
/api/admin/livestream-gift-histories |
Gift history |
2.9 Payment & Finance
| Controller |
Endpoint prefix |
Mô tả |
ExchangeRateController |
/api/admin/exchange-rates |
Exchange rate management |
PaymentSettingController |
/api/admin/payment-settings |
Payment gateway settings |
ServiceChargeController |
/api/admin/service-charges |
Service charge config |
TaxController |
/api/admin/taxes |
Tax config |
TransactionProfitController |
/api/admin/transaction-profits |
Transaction profit reports |
DailyTransactionProfitSummaryController |
/api/admin/daily-transaction-profit-summaries |
Daily summaries |
RevenueSharingController |
/api/admin/revenue-sharings |
Revenue sharing config |
MonthlyPayoutSettingController |
/api/admin/monthly-payout-settings |
Monthly payout settings |
PaymasterTransactionController |
/api/admin/paymaster-transactions |
Paymaster (web3) transactions |
WebHookController |
/api/admin/webhooks |
Webhook handlers (paymaster) |
UserPaymentHistoryController |
/api/admin/user-payment-histories |
User payment history |
2.10 System Config & Maintenance
| Controller |
Endpoint prefix |
Mô tả |
SystemSettingController |
/api/admin/system-settings |
System-wide settings, wallet info |
SystemMaintenanceController |
/api/admin/system-maintenances |
Maintenance mode management |
UserWhiteListController |
/api/admin/user-whitelists |
Maintenance whitelist |
SystemEnvironmentController |
/api/admin/system-environments |
Environment variables |
SystemMasterDataController |
/api/admin/system-master-data |
Master data CRUD |
FeatureToggleController |
/api/admin/feature-toggles |
Feature flag management |
VersionManagementController |
/api/admin/version-managements |
App version management |
AppDriverConfigController |
/api/admin/app-driver-configs |
App driver (IoT) config |
TriggerBatchController |
/api/admin/trigger-batch |
Manual batch job triggers |
UploadController |
/api/admin/uploads |
File upload (S3) |
MasterDataController |
/api/admin/master-data |
Master data bulk operations |
2.11 Dashboard & Analytics
| Controller |
Endpoint prefix |
Mô tả |
DashboardController |
/api/admin/dashboard |
KPI dashboard (amount, NFT summary, machine state, event summary) |
DashboardActiveUserTriggerController |
/api/admin/dashboard/active-user-trigger |
Trigger active user summary |
2.12 Other
| Controller |
Endpoint prefix |
Mô tả |
GameplayTypeController |
/api/admin/gameplay-types |
Gameplay type config |
SkillRankController |
/api/admin/skill-ranks |
Skill rank config |
SkillPointController |
/api/admin/skill-points |
Skill point config |
RarityController |
/api/admin/rarities |
Rarity config (life gauge, energy gauge settings) |
LevelPlayConfigController |
/api/admin/level-play-configs |
Level play config |
LevelRequiredController |
/api/admin/level-requireds |
Level requirements |
NewsController |
/api/admin/news |
News management |
BannerController |
/api/admin/banners |
Banner management |
BackgroundController |
/api/admin/backgrounds |
Background images |
RoomController |
/api/admin/rooms |
Room history/management |
RoomUserHistoryController |
/api/admin/room-user-histories |
Room user history |
FeedbackController |
/api/admin/feedbacks |
User feedback |
CheatController |
/api/admin/cheats |
Cheat detection/management |
GimmickController |
/api/admin/gimmicks |
Gimmick config |
ProductController |
/api/admin/products |
Product management |
PhraseController |
/api/admin/phrases |
User condition phrase triggers |
ReferralRewardController |
/api/admin/referral-rewards |
Referral reward config |
TapjoyConfigController |
/api/admin/tapjoy-configs |
Tapjoy ad network config |
AdvertisingConfigController |
/api/admin/advertising-configs |
Advertising config |
InvitationCardController |
/api/admin/invitation-cards |
Invitation card config |
MasterPublicKeyController |
/api/admin/master-public-keys |
Blockchain public keys |
CoinConsumptionPriorityController |
/api/admin/coin-consumption-priorities |
Coin consumption priority |
PlayFeeController |
/api/admin/play-fees |
Play fee config |
LicensorController |
/api/admin/licensors |
Licensor management |
3. Admin JMS Listeners
| Listener |
Queue |
Mô tả |
JMSUserMissionProgressListener |
mission progress queue |
Cập nhật mission progress |
JMSUserOnlineMessageListener |
user online queue |
Theo dõi user online |
JMSTriggerActiveUserListener |
active user trigger queue |
Trigger active user summary |
JMSUserMissionProgressRewardListener |
mission reward queue |
Mission reward distribution |
JMSIotDeviceListener |
IoT device queue |
IoT device events |
JMSPaymasterTransactionListener |
paymaster transaction queue |
Web3 paymaster events |
JMSIotDeviceSchedulingMessageListener |
IoT scheduling queue |
IoT device scheduling |
JMSCheckStatusMachineCancelRoomMessageListener |
machine cancel room queue |
Machine cancel room events |
JMSUserConditionPhraseListener |
condition phrase queue |
User condition phrase events |
UserSendMailLogListener |
mail log queue |
Mail sending log |
4. Functional requirements
| ID |
Requirement |
Chi tiết |
| ADM-F-01 |
Admin auth riêng |
Email/password login, JWT riêng với user JWT (SecurityJwtService) |
| ADM-F-02 |
RBAC |
Role-based access control qua RoleEnum, RuleEnum |
| ADM-F-03 |
Machine state control |
Admin có thể change machine state, game mode, group qua API |
| ADM-F-04 |
Manual batch trigger |
TriggerBatchController cho phép admin trigger batch jobs thủ công |
| ADM-F-05 |
Feature toggles |
Runtime enable/disable features |
| ADM-F-06 |
Cheat detection |
CheatController + AddCoinUserRequest cho ops team |
| ADM-F-07 |
Maintenance mode |
SystemMaintenanceController set maintenance + whitelist users |
| ADM-F-08 |
File upload |
UploadController lên S3 cho assets (banner, background, NFT metadata) |
| ADM-F-09 |
Dashboard KPIs |
Amount summary, NFT summary, machine state, event summary, active users |
| ADM-F-10 |
Init data |
InitController + InitializeData seed master data khi deploy lần đầu |
5. Acceptance criteria
- [ ] Admin login với email/password → nhận JWT, JWT works cho admin APIs
- [ ] Unauthorized request → 401
- [ ] Admin với wrong role → 403
- [ ] Machine state change → machine nhận command qua WebSocket/IoT
- [ ] Feature toggle ON → feature available; OFF → feature disabled
- [ ] Maintenance mode ON → non-whitelist users nhận maintenance response
- [ ] Manual batch trigger → job chạy và log kết quả
- [ ] File upload → file available trên S3 URL
6. Code references
admin/src/main/java/com/figpop/
AdminApplication.java
admin/controller/ # 100+ controllers
admin/jms/ # 10 JMS listeners
admin/aop/AdminRequestAspect.java
admin/config/
admin/init/ # InitializeData, InitialService
admin/mapper/ # 60+ ModelMappers