Routes & Pages

Định nghĩa trong src/App.tsx. Tất cả route protected được bọc bởi ProtectedRoute + AppLayout (trừ payment return pages).

---

Public routes (không cần auth)

Route	Component	Mục đích
/login	LoginPage	Đăng nhập username/email + password; OTP 2FA; Turnstile
/forgot-password	ForgotPasswordContactPage	Nhập email/phone để nhận OTP
/forgot-password/otp	ForgotPasswordOtpPage	Xác minh OTP
/forgot-password/reset	ForgotPasswordResetPage	Đặt mật khẩu mới

---

Protected routes

Route	Component	Mục đích
/	DashboardPage	Trang chủ: số dư, thống kê, mua credit, phân phối credit
/shops	ShopsPage	Danh sách shop, tạo shop, suspend/unsuspend, phân phối credit
/shops/:shopId	ShopDetailPageRedesign	Chi tiết shop: overview, security, ledgers, game mappings
/players	PlayersPage	Danh sách players, filter theo shop/username/phone/email
/players/:playerId	AgentPlayerDetailPage	Chi tiết player + lịch sử giao dịch
/transactions	AgentTransactionsPage	Sổ credits (ledger), filter, export CSV
/online-transactions	OnlineBalanceTransactionsPage	Sổ USD wallet, rút crypto, export
/provider-fees	ProviderFeesPage	Xem bảng phí provider (read-only)
/fraud-indicators	FraudIndicatorsPage	Cờ gian lận player, phân tích, resolve
/popups/send	SendShopPopupPage	Gửi in-app popup tới shop/player
/broadcasts/send	SendBroadcastPage	Gửi broadcast notification
/settings	SettingsPage	Cost rate, cảnh báo số dư thấp, bật 2FA
/payment/success	AgentPaymentSuccessPage	Callback thanh toán thành công
/payment/cancelled	AgentPaymentCancelledPage	Callback hủy thanh toán
/payment/error	AgentPaymentErrorPage	Callback lỗi thanh toán

---

Redirect routes

Route	Redirect	Ghi chú
/purchase	→ /	Legacy
* (catch-all)	→ /

note

ShopDetailPage.tsx (bản cũ) vẫn tồn tại trong repo nhưng route dùng ShopDetailPageRedesign.tsx.

---

Điều kiện hiển thị menu

Send popup / Send broadcast

Chỉ hiển thị khi can_delegate_popups === true (từ dashboard API hoặc user profile).

Logic trong AppLayout.tsx tương tự Shop Portal.

---

Shop detail tabs (/shops/:shopId)

Tab	Nội dung
Overview	Thông tin shop, wallets (credit + USD)
Security	Đổi tên, password, cost rate, popup permission
Credit transactions	Ledger credits + modal chi tiết
USD transactions	Online balance ledger
Games	Bật/tắt game providers cho shop

---

Components theo domain

Layout & Shell

Component	File	Vai trò
AppLayout	components/layout/AppLayout.tsx	Sidebar, bottom nav mobile, balance cards, nav, notification bell
AgentPageLayout	components/layout/AgentPageLayout.tsx	Frame nội dung page: title, description, actions
ProtectedRoute	components/auth/ProtectedRoute.tsx	Guard auth, redirect /login
PortalEmptyState	components/ui/PortalEmptyState.tsx	Empty state UI

Auth

Component	Vai trò
LoginPage	Login + OTP 2FA + Turnstile
ForgotPassword*Page	3-step password reset
VerifyNowTrigger	Modal xác minh email/phone agent

Credits & Finance

Component	Vai trò
CreditPurchaseTrigger/Modal	Mua credit (crypto / convert USD)
DistributeCreditsTrigger	Phân phối credit xuống shop
WithdrawCreditsFromShopTrigger	Rút credit từ shop về agent
AvailableCreditsCallout	Hiển thị số dư credit
PortalWithdrawalLimitsPanel	Giới hạn rút USD/ngày
CurrencyIcon	Icon crypto (BTC, DOGE, LTC, Cash App)

Shops

Component	Vai trò
ShopGovernanceModal	Confirm suspend/unsuspend
shopStatusBadge	Badge trạng thái shop

Notifications

Component	Vai trò
AgentNotificationBell	Bell icon + dropdown broadcasts (poll 2 phút)
AgentInAppPopupGate	Gate hiển thị in-app popup modal
BroadcastMessageBody	Render nội dung broadcast/popup

Dashboard & Players

Component	Vai trò
AgentHierarchyMiniTree	Cây hierarchy shop + stats theo ngày
AgentPlayerDetailPanel	Panel chi tiết player

---

Payment return flow

Backend redirect về Agent Portal sau thanh toán:

/payment/success?transaction_id=...&status=...
/payment/cancelled?transaction_id=...
/payment/error?message=...

Query params: transaction_id, status, message.