Giao diện dành riêng cho Đại Lý — nhà phân phối khu vực quản lý mạng lưới shop gaming, mua/phân phối credits, ví USD online, giám sát giao dịch tiền mặt và giao tiếp với hệ sinh thái kiosk.
Agent là tầng thứ hai trong chuỗi phân cấp bốn lớp của KioskGaming. Mỗi Agent phụ trách nhiều Shop và tiếp nhận credits từ SuperAgent hoặc nền tảng.
Agent (Đại Lý): Nhà phân phối khu vực. Mua credits từ SuperAgent/platform, bán credits cho shop qua giao dịch tiền mặt (cash-credits), thiết lập costRate cho từng shop và giám sát ví credit + ví USD online.
Chuỗi B2B: SuperAgent → Agent → Shop → Cashier → Player. Credits chảy xuống; tiền mặt/USD chảy ngược lên theo costRate.
Repo lưu ý: Thư mục lồng kioskgaming_backend/ chỉ là bản clone backend tham khảo — frontend gọi API qua REACT_APP_API_BASE_URL, không import code backend.
Quy trình vận hành tiêu chuẩn của một Agent từ khi mua credits đến khi giám sát hiệu suất shop.
Agent mở CreditPurchaseModal, chọn số lượng và phương thức thanh toán (ZeroX crypto, eCash, chuyển khoản ngân hàng…). Sau khi thanh toán xong, credits được cộng vào ví của Agent.
Từ trang chi tiết shop, Agent dùng SellCreditsCashToShopTrigger
(SellCreditsCashModal từ @kioskgaming/ui) gọi
POST /agent/shops/:id/cash-credits — ghi nhận tiền mặt shop trả
và phân phối credits đồng thời.
Agent tạo shop mới với thông tin: tên, email, số điện thoại, mật khẩu và costRate — tỷ lệ thập phân (0.05 = 5%) Agent thu trên mỗi credit giao cho shop đó.
Dashboard hiển thị số dư credits, danh sách shops, số lượng players, giao dịch gần đây và AgentHierarchyMiniTree — cây phân cấp trực quan Agent → Shops.
Nếu shop vi phạm, Agent dùng ShopGovernanceModal để tạm ngưng (Suspend), mở lại (Unsuspend) hoặc chấm dứt hợp đồng (Terminate) một shop.
Agent có toàn quyền CRUD đối với các Shop thuộc phạm vi của mình, bao gồm thiết lập giá và kiểm soát trạng thái hoạt động.
Form sử dụng react-hook-form v7. Các trường: tên, username, email, phone, password và costRate (% → cost_rate thập phân). File: ShopsPage.tsx
Liệt kê tất cả shops với trạng thái, số dư credits, số players và nút hành động nhanh. Hỗ trợ phân phối credits trực tiếp từ danh sách.
Route /shops/:shopId dùng ShopDetailPageRedesign.tsx (import alias ShopDetailPage). Hiển thị ví credit/USD shop, game mapping, bán/rút credits.
ShopGovernanceModal.tsx cung cấp ba hành động quản trị với xác nhận: Suspend, Unsuspend, Terminate.
costRate là số thập phân 0–1 (vd 0.05 = 5%). Shop phải có costRate lớn hơn costRate của Agent.
Tiền shop nợ = credits × shopCostRate; lợi nhuận agent = credits × (shopCostRate − agentCostRate).
Dùng formatCostRate() và percentInputToRate() trong costFormat.ts.
| Trạng thái Shop | Hiển thị | Agent có thể làm | Giao dịch |
|---|---|---|---|
| Active | Badge xanh lá | Phân phối credits, xem chi tiết, Suspend / Terminate | Bình thường |
| Suspended | Badge vàng | Unsuspend, Terminate, xem chi tiết | Bị chặn |
| Terminated | Badge đỏ | Chỉ xem — không thể phục hồi | Đã đóng |
Credits là đơn vị tiền tệ trung gian trong hệ thống. Agent mua credits từ nền tảng và phân phối xuống các shop để shop phục vụ players. Đây là luồng tiền tệ cốt lõi của toàn bộ hệ sinh thái.
Số dư credit_balance trên dashboard. Mua qua CreditPurchaseModal, chuyển đổi từ USD qua convertBalanceToCredits. Ledger tại /transactions.
online_balance_net — hoa hồng/tiền mặt tích lũy. Trang /online-transactions, rút crypto qua OTP + createAgentOnlineBalanceWithdrawal.
Agent nhập hoặc chọn số tiền muốn mua. Với eCash, chỉ được chọn từ danh sách cố định (ECASH_APP_ALLOWED_AMOUNTS).
Hiển thị các tùy chọn: ZeroX crypto, eCash app, chuyển khoản ngân hàng, v.v. Mỗi phương thức có UI riêng biệt.
Modal nhúng iframe checkout provider + nút mở tab mới. ZeroX static wallets qua /agent/payments/zeroxprocessing/static-wallets.
AgentPaymentReturnPage.tsx nhận redirect sau khi thanh toán. Credits được cộng vào ví Agent.
ZeroX Crypto — Thanh toán tiền điện tử. Hiển thị địa chỉ ví, QR code. Options định nghĩa tại ZEROX_PAYMENT_OPTIONS.
eCash App — Ứng dụng thanh toán nội bộ. Chỉ nhận các mệnh giá được liệt kê trong ECASH_APP_ALLOWED_AMOUNTS.
Bank Transfer — Chuyển khoản ngân hàng truyền thống với thông tin tài khoản được cung cấp.
SellCreditsCashToShopTrigger trên Shop Detail gọi createShopCashCredits. Ghi cash transaction + phân phối credits một lần.
WithdrawCreditsFromShopTrigger → POST /agent/shops/:id/credits/withdraw. Hoàn credits về ví agent khi cần.
Agent có nhiều kênh giao tiếp với shops và players: broadcast toàn hệ thống, popup định mục tiêu và notification bell thời gian thực.
Gửi thông điệp broadcast đến tất cả shops/players thuộc Agent. Hỗ trợ link markup được xử lý bởi broadcastLinkMarkup.ts.
Gửi popup thông báo đến một shop cụ thể. Phù hợp cho cảnh báo riêng tư, thông báo khuyến mãi theo shop.
Icon chuông với badge đếm số thông báo chưa đọc. Hiển thị ở header mọi trang. Demo: 🔔 3 Thông báo
AgentInAppPopupGate.tsx là một wrapper component đặt ở cấp cao trong cây component. Nó lắng nghe các broadcast/popup đến từ server và tự động chặn màn hình để hiển thị thông điệp trước khi Agent tiếp tục dùng app.
broadcastLinkMarkup.ts: Parser chuyển đổi cú pháp link đặc biệt trong nội dung broadcast thành các thẻ HTML anchor có thể click được. BroadcastMessageBody.tsx render kết quả đã parse.
Nhập nội dung, có thể dùng link markup [text](url).
Backend gửi thông điệp đến tất cả shops/players thuộc Agent.
Shops/players nhận popup overlay khi đăng nhập hoặc theo thời gian thực.
Trang chủ Dashboard (DashboardPage.tsx) là trung tâm điều hành của Agent — cung cấp
cái nhìn tổng quan tức thì về toàn bộ mạng lưới.
AgentHierarchyMiniTree.tsx — cây phân cấp dạng thu gọn hiển thị ngay trên Dashboard. Visualize mối quan hệ Agent → Shops với số liệu tóm tắt từng nhánh.
AvailableCreditsCallout.tsx — khối nổi bật hiển thị số dư credits hiện tại của Agent, kèm nút "Mua Credits" và "Phân phối" để truy cập nhanh.
AgentHomeRecentTransactions.tsx — bảng giao dịch gần nhất hiển thị trên Dashboard. Liệt kê loại, số tiền, shop liên quan và thời gian.
Trang lịch sử giao dịch đầy đủ (AgentTransactionsPage.tsx) với filter theo thời gian, loại giao dịch và shop.
| Widget | Component | Dữ liệu hiển thị | Action |
|---|---|---|---|
| Credit Balance | AvailableCreditsCallout |
Số dư ví Agent | Mua / Phân phối |
| Shops Overview | DashboardPage |
Tổng shops, active / suspended | Xem chi tiết |
| Players Count | DashboardPage |
Tổng players dưới tất cả shops | Xem PlayersPage |
| Recent Transactions | AgentHomeRecentTransactions |
5–10 giao dịch gần nhất | Xem tất cả |
| Hierarchy Tree | AgentHierarchyMiniTree |
Cây Agent → Shops | Drill-down shop |
Stack kỹ thuật, cấu trúc thư mục, các utilities quan trọng và tích hợp thanh toán ZeroX.
// Chuyển % hiển thị → rate nội bộ
percentInputToRate(5) // "5%" → 0.05
// Format rate nội bộ → hiển thị
formatCostRate(0.05) // 0.05 → "5%"// eCash: chỉ cho phép mệnh giá cố định
ECASH_APP_ALLOWED_AMOUNTS = [
50, 100, 200, 500, 1000
]
// ZeroX: tùy chọn crypto
ZEROX_PAYMENT_OPTIONS = [
{ id: 'eth', label: 'Ethereum' },
{ id: 'usdt', label: 'USDT' },
...
]ZeroX là tích hợp thanh toán crypto của nền tảng. Agent chọn token (ETH, USDT…), hệ thống hiển thị địa chỉ ví và QR code. Sau khi on-chain transaction xác nhận, webhook backend cập nhật số dư Agent tự động.
sanitizeUser.ts làm sạch dữ liệu user trước khi hiển thị — loại bỏ thông tin nhạy cảm, chuẩn hóa tên trường. Dùng trước khi render bất kỳ object user nào ra UI.
| Route | Component | Chức năng |
|---|---|---|
/ |
DashboardPage |
Trang chủ — credit + USD balance |
/transactions |
AgentTransactionsPage |
Ledger ví credit |
/online-transactions |
OnlineBalanceTransactionsPage |
Ledger ví USD + rút tiền |
/cash-transactions |
CashTransactionsLedgerPage |
Giao dịch tiền mặt với shop |
/provider-fees |
ProviderFeesPage |
Phí provider (read-only) |
/fraud-indicators |
FraudIndicatorsPage |
Cảnh báo gian lận player |
/shops |
ShopsPage |
Danh sách + tạo shop |
/shops/:shopId |
ShopDetailPageRedesign |
Chi tiết shop + bán/rút credits |
/players |
PlayersPage |
Players (read-only) |
/broadcasts/send |
SendBroadcastPage |
Gửi broadcast |
/popups/send |
SendShopPopupPage |
Gửi popup in-app |
/settings |
SettingsPage |
2FA, cảnh báo số dư, xác minh |
/payment/{success,cancelled,error} |
AgentPayment*Page |
Callback sau thanh toán online |
Agent có tầm nhìn (visibility) toàn bộ players thuộc tất cả shops trong mạng lưới, nhưng không can thiệp trực tiếp vào tài khoản player.
Liệt kê tất cả players trên tất cả shops của Agent. Có thể lọc theo shop, trạng thái. Hiển thị username, shop nguồn, số dư, ngày đăng ký.
Xem chi tiết một player: thông tin cá nhân, lịch sử giao dịch, session gần đây, shop nào quản lý. Read-only từ phía Agent.
Lưu ý phân quyền: Agent không có quyền tạo, chỉnh sửa hay xóa player. Players được tạo bởi Shop hoặc tự đăng ký. Agent chỉ có quyền xem player trong phạm vi mạng lưới của mình.
Dashboard, Shops, ShopDetail, Players, Transactions, Online/Cash transactions, Provider fees, Fraud, Broadcast, Popup, Settings, Payment return
/agent/*, /agent-auth/* qua Axios singleton services/api.ts → backend B2B routes
craco start/build · packages file:../packages/ui + page-loading · PORT 3003
Credit CDN + USD online balance; mua online, bán cash cho shop, rút crypto
SuperAgent → Agent → Shop → Cashier → Player
Xem 04+ Chi tiết kỹ thuật — endpoint đầy đủ, auth, cookbook