Kỹ thuật chi tiết — Agent Portal

Stack & tư duy tổng thể

App này khác hẳn kiosk frontend (Next.js): đây là một SPA quản trị B2B chạy trên Create React App. Nắm 6 đặc điểm sau trước khi đọc code — chúng giải thích phần lớn cấu trúc.

Cấu trúc thư mục src/

Phân lớp rõ: pages/ (route đích) → components/ (theo domain) → services/ + hooks/ + utils/. Hai file trung tâm: services/api.ts và types/index.ts.

Bản đồ route & bảo vệ route

App.tsx dùng BrowserRouter + Routes. Mọi route nghiệp vụ đều bọc trong <ProtectedRoute>; chỉ /login là public. Catch-all * và /purchase đều Navigate về /.

const { isAuthenticated, isLoading } = useAuth();
if (isLoading) return <PageLoadingIndicator variant="section" />;  // chờ đọc localStorage
if (!isAuthenticated)
  return <Navigate to="/login" replace state={{ from: location }} />;
return <>{children}</>;

Luồng đăng nhập & JWT

Đăng nhập 1 bước (email + password, không cần mã email như kiosk). Token và profile lưu localStorage; AuthProvider khởi tạo state từ đó khi mở app.

services/api.ts — bộ não giao tiếp

Một AxiosInstance duy nhất, mỗi endpoint là một hàm export. Request interceptor tự gắn token; response interceptor bắt 401. Không có lớp service trung gian như kiosk — page/component gọi thẳng các hàm này.

client.interceptors.request.use((config) => {
  const token = localStorage.getItem(STORAGE_KEYS.AUTH_TOKEN);
  if (token) config.headers.Authorization = `Bearer ${token}`;
  return config;
});

client.interceptors.response.use((res) => res, (error) => {
  if (error.response?.status === 401)
    window.dispatchEvent(new Event('auth:unauthorized'));
  return Promise.reject(error);
});

Bảng endpoint đầy đủ (prefix base /api)

types/index.ts — shape dữ liệu domain

Type quan trọng nhất xoay quanh ví và cost. Lưu ý nhiều field có cả camelCase lẫn snake_case do backend trả không nhất quán — code phải phòng cả hai.

interface AgentProfile {
  id: string; email: string; name: string; status: string;
  costRate?: number;          // rate mua vào của agent (0–1)
}

interface AgentDashboardData {
  credit_balance: number; active_shops_count: number;
  low_balance_warning_enabled?: boolean; /* ... cờ quyền popup ... */
}

interface AgentWalletLedgerEntry {      // 1 dòng /agent/transactions
  id: string; type: string; amount: number | null;
  direction: 'in' | 'out' | 'unknown';
  counterparty: { ownerType: string; ownerId: string } | null;
  costRate?: number; costAmount?: number;   // commission ghi ở từng dòng
  platformFeeRate?: number; platformFeeAmount?: number;
  createdAt?: string; created_at?: string;   // ⚠ cả 2 kiểu
}

interface AgentShop {
  id: string; name: string; status: AgentShopStatus;
  costRate?: string | number;          // ⚠ string HOẶC number
  minShopCostRateExclusive?: number; // cost shop phải > mức này
}

costRate & commission — mô hình lời của Agent

Đây là khái niệm quan trọng nhất của repo. Agent kiếm tiền nhờ chênh lệch cost rate: mua credit rẻ (theo agentCostRate), giao cho shop với giá đắt hơn (theo shopCostRate). Phần chênh là hoa hồng.

# Khi AGENT MUA credit từ platform:
estimatedCharge (USD) = credits × agentCostRate
                        # vd 100 credit × 0.30 = trả 30 USD cho provider

# Khi AGENT GIAO credit cho shop:
cashShopOwesAgent (USD) = credits × shopCostRate
                        # vd 100 credit × 0.50 = shop nợ agent 50 USD

# ⇒ LỢI NHUẬN agent / 100 credit:
margin = credits × (shopCostRate − agentCostRate)   # = 100 × (0.50 − 0.30) = 20 USD

utils/costFormat.ts — chuyển đổi % ⇄ rate

// rate (0.05) → hiển thị "5%"  (Intl.NumberFormat style:'percent')
export function formatCostRate(raw: string|number|null|undefined): string

// input "5" (người dùng gõ %) → rate 0.05, clamp [0,100]
export function percentInputToRate(percentStr: string): number {
  const pct = parseFloat(percentStr);
  return Math.min(100, Math.max(0, pct)) / 100;
}

CreditPurchaseModal — mua credit từ platform

Modal toàn màn hình (components/credits/CreditPurchaseModal.tsx). Người dùng nhập số credit muốn nhận, chọn phương thức, hệ thống ước tính tiền phải trả rồi tạo order và nhúng trang thanh toán provider.

Mapping phương thức UI → API

export const ECASH_APP_ALLOWED_AMOUNTS = [25,31,40,50,60,100,125,130,150,200,300,400,500];

export function mapUiPaymentIdToAgentPaymentMethod(id: string) {
  if (id.startsWith('zerox_')) return id;   // zerox_usdt, zerox_btc...
  return { btcpay: 'btc_onchain', ltc_btcpay: 'ltc_chain',
           doge_btcpay: 'doge_chain', py_usd: 'pyusd',
           cashapp: 'ecash_app' }[id] ?? id;
}

SellCreditsCashToShopTrigger — cash-credits flow

Thay cho phân phối credit "miễn phí" cũ, agent bán credit qua POST /agent/shops/:id/cash-credits. UI dùng SellCreditsCashModal từ @kioskgaming/ui.

// Payload: credits, payment_method?, received_at?, note?
await createShopCashCredits(shopId, { credits: 100, payment_method: 'cash' });
// → ghi cash-transaction + trừ agent credit + cộng shop credit

Vòng đời & governance của shop

ShopsPage (danh sách + tạo) và ShopDetailPageRedesign (chi tiết) là nơi agent thực thi toàn quyền CRUD trên shop của mình, gồm đặt giá (cost), reset mật khẩu, bật game và quản trị trạng thái.

ShopGovernanceModal — xác nhận hành động nguy hiểm

Dùng Modal từ @kioskgaming/ui với variant='delete' cho terminate (cảnh báo đỏ "irreversible") và variant='confirm' cho suspend (cảnh báo vàng). Callback onConfirmSuspend/Terminate trả Promise<boolean>; chỉ đóng modal khi thành công.

Lịch sử ví & agentWalletLedger.ts

AgentTransactionsPage dùng hook useAgentTransactions({page, limit}) (mặc định limit 25) gọi /agent/transactions. Vì shape ledger phức tạp, mọi logic hiển thị gom vào utils/agentWalletLedger.ts.

Players — chỉ đọc

Agent không tạo/sửa/xoá player. PlayersPage (/agent/players) liệt kê toàn bộ player thuộc mọi shop; AgentPlayerDetailPage + AgentPlayerDetailPanel hiển thị hồ sơ + số dư + lịch sử ví (/agent/players/:id/transactions).

Hai hệ thống thông báo riêng biệt

Dễ nhầm: app có 2 cơ chế khác nhau với endpoint khác nhau. Một là chuông thông báo (không chặn), hai là popup chặn màn hình.

Markup link trong broadcast

utils/broadcastLinkMarkup.ts parse cú pháp <link>label|https://...</link> thành segment text/link an toàn (chỉ chấp nhận http/https qua sanitizeBroadcastUrl). BroadcastMessageBody.tsx render kết quả — dùng chung cho cả chuông và popup gate.

Styling, config & build

Tailwind v3 có file config (khác kiosk v4), kết hợp design token HSL của package UI dùng chung. Config app gói gọn trong config/env.ts + constants/index.ts.

Cookbook cho dev mới

Các tác vụ phổ biến theo đúng quy ước của repo.

Bẫy thường gặp (đọc trước khi sửa)