Kỹ thuật chi tiết — Cashier App

Stack & tư duy tổng thể

Khác hẳn Kiosk Frontend (Next.js, state machine in-memory): đây là một Create React App cổ điển được Capacitor đóng gói thành app Android cho nhân viên quầy. Nắm 6 đặc điểm "lạ" sau trước khi đọc code.

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

Cây thư mục phẳng theo chuẩn CRA: pages/ cho từng màn hình, components/, services/, hooks/, utils/. Alias @/ KHÔNG được dùng — import bằng đường dẫn tương đối.

Màn hình khởi động: index.tsx → App.tsx

Một SPA CRA bình thường: bootstrap React vào #root, đặt tiêu đề tab, đăng ký service worker, rồi để router quyết định màn hình.

document.title = ENV.APP_NAME;

const root = ReactDOM.createRoot(document.getElementById('root') as HTMLElement);
root.render(
  <React.StrictMode><App /></React.StrictMode>
);

registerServiceWorker(); // PWA/offline shell

Router & route bảo vệ

Toàn bộ định nghĩa trong App.tsx. Mỗi màn hình nghiệp vụ được bọc <Protected> (chính là CashierProtectedRoute). Route public chỉ có /login.

const { isAuthenticated, isLoading } = useCashierAuth();

if (isLoading) return <PageLoadingIndicator variant="section" />;

if (!isAuthenticated)
  return <Navigate to="/login" replace state={{ from: location }} />;

return <>{children}</>;

Auth, token & định danh thiết bị

Auth của cashier tách biệt hoàn toàn với Shop Admin (key localStorage khác nhau). Mỗi lần đăng nhập gắn kèm một device fingerprint và phải đăng ký thiết bị để quản lý cửa hàng duyệt.

cashierApi.ts — axios singleton

Một AxiosInstance tạo sẵn với baseURL, timeout 15s, và 2 interceptor. Mọi hàm API là export thuần (không phải class), đa số bọc try/catch trả về một envelope chuẩn.

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

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

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

Bảng endpoint backend (sau baseURL đã gồm /api)

Denomination engine

Trái tim của mọi thao tác quỹ. utils/denominations.ts giữ hằng số + công thức; components/DenominationGrid.tsx là UI tái dùng ở Opening, Cash drop, Closing và Handover.

export function computeDenominationTotal(items: DenominationItem[]): number {
  const total = items.reduce(
    (sum, i) => sum + i.denomination * i.quantity, 0);
  return Math.round(total * 100) / 100; // tránh lỗi float
}

Vòng đời ca & các status

App không có một state machine tập trung như kiosk frontend; thay vào đó "máy trạng thái" nằm ở backend qua trường shift.status, còn frontend phản ứng bằng cách redirect và bật/tắt nút.

Trạng thái khác xuất hiện trong UI: auto_locked, suspended, no_show, cancelled. Trong code, "ca thao tác được" = ['active','auto_locked','suspended'].

Đóng ca kiểu "blind close"

const res = await cashierCloseShiftBlind(id, { denominations: items });
// Số kỳ vọng KHÔNG hiển thị cho tới khi submit xong:
res.data = { actualClosingCash, expectedClosingCash,
            discrepancyAmount, discrepancyFlagged, status };

Deposit / Redeem trong ActiveShiftPage

Màn hình làm việc lõi: tra cứu người chơi (debounce 250ms), nạp credits, đổi credits, tạo người chơi mới qua modal. Tất cả nút giao dịch chỉ bật khi canOperate === true.

useEffect(() => {
  const t = setTimeout(() => void loadPlayers(), 250);
  return () => clearTimeout(t);
}, [search]); // gõ phím → chờ 250ms → GET /cashier/players

Handover & Cash drop

Hai thao tác quỹ phụ, đều xoay quanh DenominationGrid. HandoverPage đặc biệt vì có 2 chế độ tự suy từ status của ca.

if (['active','auto_locked','suspended'].includes(current.status))
  setMode('initiate');
else if (current.status === 'scheduled')
  setMode('confirm');
else setMode('none'); // không cho bàn giao

Capacitor / Android — điểm khác biệt lớn nhất

Đây là thứ khiến repo này khác mọi app web khác trong hệ thống: nó được đóng gói thành APK Android chạy trên tablet quầy. Nhưng có một bất ngờ quan trọng về cách app nạp nội dung.

const remoteUrl = process.env.CAP_SERVER_URL?.trim()
  || 'https://cashier.kioskservice.club/';

const config: CapacitorConfig = {
  appId: 'club.kioskservice.kioskgaming.cashier',
  appName, // '[Dev] Cashier...' hoặc 'Cashier - Kiosk Gaming'
  webDir: 'build',
  server: {
    url: remoteUrl, // ★ nạp từ web LIVE, không từ build local!
    allowNavigation: ['dev-cashier.kioskservice.club', 'cashier.kioskservice.club'],
  },
};

Build flow thực tế (script trong package.json)

# DEV: trỏ WebView về dev-cashier + đổi tên "[Dev] ..."
npm run apk:dev
#  └→ CAP_SERVER_URL=https://dev-cashier... cap sync android
#     && node scripts/set-android-app-name.js dev
#     && cd android && ./gradlew assembleDebug

# PROD: trỏ về cashier.kioskservice.club
npm run apk:prod   # = apk (mặc định)

Tailwind v3 & CRACO

Khác kiosk frontend (Tailwind v4 không config): đây là Tailwind v3 có tailwind.config.js + postcss.config.js, dùng design token kiểu hsl(var(--…)). Build qua CRACO để vá webpack.

const patch = require('../packages/ui/scripts/craco-patch-source-map-loader-ui.cjs');

module.exports = {
  webpack: {
    configure: (cfg) => { patch(cfg); return cfg; },
  },
};

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

Tập trung ở src/config/env.ts. Theo chuẩn CRA, biến phải có tiền tố REACT_APP_ mới lọt vào bundle (khác Next.js dùng NEXT_PUBLIC_).

Thiết lập kiểm thử

Repo có bộ @testing-library/* qua CRA/Jest nhưng hiện chưa có test file thực tế trong codebase.

npm start          # craco start → http://localhost:3000
npm run build      # craco build → thư mục build/
npm test           # craco test (Jest watch)
npm run apk:prod   # cap sync + gradlew assembleDebug

Cookbook cho dev mới

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

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