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

Stack & tư duy tổng thể

Trước khi đọc code, hãy nắm 6 đặc điểm "khác biệt" nhất của app này — đặc biệt so với app Kiosk Frontend (Next.js) đã mô tả ở báo cáo 02. Hiểu chúng rồi thì đọc code rất nhanh.

Shop trong chuỗi B2B: Agent → Shop → Cashier → Player

Shop là tầng trung gian: nhận credits từ Agent (theo tỉ giá), rồi phân phối credits xuống Player tại địa điểm kinh doanh. Cashier là người vận hành tại quầy. Việc kiếm USD đến từ chênh lệch giá khi nạp cho player.

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

Cây thư mục phẳng theo phong cách CRA. Quy ước: page PascalCase trong pages/, component dùng chung trong components/, không có alias @/* — import bằng đường dẫn tương đối.

Màn hình khởi động & mô hình render

Là CRA SPA thuần client (không SSR). index.tsx render <App/> trong StrictMode và đăng ký service worker (PWA).

Routing & ProtectedRoute

Tất cả route khai báo phẳng trong App.tsx. Không route group, không nested layout (layout nằm trong từng page qua <AppLayout>). Mọi route trừ /login đều bọc <ProtectedRoute>.

const { isAuthenticated, isLoading } = useAuth();
const location = useLocation();

if (isLoading) return <PageLoadingIndicator variant="section" />;  // chờ khôi phục phiên
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 + mật khẩu (+ Turnstile tùy chọn). Token JWT lưu localStorage. Phiên shop tách biệt hoàn toàn với hệ Admin (key riêng, không chia sẻ cookie).

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

Một file duy nhất export ~35 hàm async, tất cả dùng chung một axios client. Component không tự gọi axios — chúng import hàm cụ thể.

const client = axios.create({ baseURL: API_BASE_URL, timeout: 15000 });

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);
});

Nhóm endpoint chính (prefix base đã có /api)

Quản lý state & đồng bộ qua custom events

Vì không có store toàn cục, app dùng DOM CustomEvent làm "event bus" để các component không cha-con cùng cập nhật (đặc biệt là số dư ví).

Tra cứu player theo số điện thoại — 4 trạng thái

Lõi nghiệp vụ nằm ở ShopPlayerLinkByPhonePanel.tsx — dùng chung cho cả modal "Create player" (flow="create") và "Transfer from another shop" (flow="transfer"). Người dùng nhập phone (qua react-phone-number-input), bấm lookup, server trả về một trong 4 status quyết định hành động tiếp theo.

Hai luồng OTP: registration vs transfer

OTP đảm bảo sự đồng ý của player trước khi thay đổi shop assignment. Cùng một panel quản 2 luồng bằng biến otpFlowMode ('registration' | 'transfer') với 2 id khác nhau: registrationId hoặc transferId.

Kênh OTP & verify (chỉ flow create)

Khi tạo player có thể chọn kênh sms hoặc email (nếu email → bắt buộc nhập email). Sau verify thành công ở flow registration, nếu response trả về data.player thì gọi onLinkedPlayer() để điều hướng sang trang chi tiết. Với flow transfer, panel còn lookup lại phone để lấy playerId mới rồi mới điều hướng.

Ví credit, cost rate & ledger

Ví shop tính bằng credits. Số dư hiện ở sidebar (AppLayout) và 4 stat card của Dashboard. Mọi biến động đọc từ GET /shop/transactions và được "trình bày" qua helper trong utils/shopWalletLedger.ts.

// Khớp backend normalizeLedgerMetadata: metadata có thể là JSON string, snake_case
export function normalizeMeta(raw: unknown): Record<string, unknown> {
  let m: unknown = raw;
  if (typeof m === 'string') { try { m = JSON.parse(m); } catch { return {}; } }
  const o = { ...(m as Record<string, unknown>) };
  if (o.player_phone != null) o.playerPhone = o.player_phone; // chuẩn hóa key
  return o;
}

ShopCreditPurchaseModal & payment provider

Trang dark UI cho shop mua thêm credits từ platform. Nhập số credits → tính USD ước tính → chọn phương thức → tạo order → nhận paymentUrl nhúng iframe.

Cấu hình subdomain cho địa điểm

Mỗi shop có 1 kiosk URL dạng label.<base>. KioskDomainPage có 3 trạng thái: chưa có (tạo), đã có (read-only + Edit), đang sửa.

// Tách label khỏi FQDN: "mystore.kioskgaming.com" + base "kioskgaming.com" → "mystore"
function subdomainLabelFromFqdn(fqdn: string, base: string): string {
  const suffix = `.${base}`;
  if (base && fqdn.endsWith(suffix)) return fqdn.slice(0, -suffix.length);
  return fqdn.split('.')[0] || '';
}

Broadcast bell & in-app popup gate

Shop vừa nhận thông báo từ Admin/Agent (chuông + popup), vừa gửi thông báo xuống player (broadcast + popup).

Tailwind 3 + workspace packages

Khác kiosk frontend (Tailwind v4 không config), app này dùng Tailwind 3.2 có file config với token màu HSL khai trong index.css. Tông chủ đạo emerald (primary 160 84% 39%).

@tailwind base; @tailwind components; @tailwind utilities;

@layer base { :root {
  --primary: 160 84% 39%;   /* emerald — dùng qua hsl(var(--primary)) */
  --border: 160 10% 90%; --radius: 0.5rem;
} }

// tailwind.config.js — content quét cả package ui đã build
content: ['./src/**/*.{js,jsx,ts,tsx}', '../packages/ui/dist/**/*.js']

Config & biến môi trường

Đọc tập trung qua src/config/env.ts. Biến phải có tiền tố REACT_APP_ (quy ước CRA). Có sẵn .env.example.

Kiểm thử & build

Hạ tầng test là mặc định của CRA (react-scripts test = Jest + RTL) nhưng chưa có file test nào trong src/. Build dùng react-scripts build (CRA có typecheck — khác kiosk frontend bỏ qua lỗi TS).

npm start    # react-scripts start → http://localhost:3004 (PORT)
npm run build  # react-scripts build (có typecheck)
npm test     # react-scripts test — hiện chưa có test case
npm run eject  # ⚠️ không nên dùng

Cookbook cho dev mới

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

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