Tính năng nghiệp vụ

1. Quản lý ví Shop

Credits wallet

Số dư chính (credit_balance) hiển thị trên sidebar và dashboard.
Dùng để cấp credits cho player (deposit).
Mọi thay đổi số dư dispatch event shop-credit-balance-refresh.

USD online balance

Ví USD riêng (online_balance_net).
Dùng để mua credits hoặc rút crypto.
Ledger riêng tại /online-transactions.

Mua credits (`ShopCreditPurchaseModal`)

Hai tab:

Tab	Luồng
Crypto	Ví tĩnh ZeroxProcessing (BTC, DOGE, LTC…), QR code, phí provider
Balance	Chuyển USD → credits theo `cost_rate`

Cost rate: tỷ lệ giá do agent đặt. credits = USD ÷ cost_rate.

flowchart LR
  A[Shop mở modal mua credits] --> B{Chọn tab}
  B -->|Crypto| C[Chọn coin → QR ví tĩnh]
  B -->|Balance| D[Nhập USD → preview credits]
  D --> E[POST /shop/convert-balance-to-credits]
  C --> F[Player gửi crypto → backend callback]

2. Quản lý Player

Danh sách (`/players`)

Tìm kiếm, phân trang.
Sort theo shop_assigned_at hoặc name.
Tạo player mới qua form hoặc ShopPlayerLinkByPhonePanel.

Tạo player

Cách	API
Trực tiếp (phone/email)	`POST /shop/players`
Đăng ký OTP (legacy transfer)	`register-initiate` → `register-verify`

Chi tiết player (`/players/:playerId`)

PlayerDetailPanel hỗ trợ:

Action	API
Deposit credits	`POST /shop/players/:id/credits` (amount > 0)
Redeem credits	`POST /shop/players/:id/credits` (amount < 0)
Ban	`POST /shop/players/:id/ban` — period: 1d/3d/7d/30d/permanent
Unban	`POST /shop/players/:id/unban`
Reissue credentials	`POST /shop/players/:id/credentials/reissue`
Xác minh phone/email	`send-verification` → `verify`
Lịch sử giao dịch	`GET /shop/players/:id/transactions`

3. Rút tiền & Phê duyệt

Player withdrawals (`/withdrawals`)

Shop duyệt/từ chối yêu cầu rút tiền của player:

GET /shop/withdrawals/pending
  → Shop xem danh sách
  → POST /shop/withdrawals/:id/approve hoặc /reject

Shop USD withdrawal (`/online-transactions`)

Luồng rút crypto từ ví USD:

sequenceDiagram
  participant S as Shop
  participant P as Shop Portal
  participant B as Backend

  S->>P: Mở form rút USD
  P->>B: GET /shop/online-balance/withdrawals/otp/eligibility
  P->>B: POST .../otp/send
  S->>P: Nhập OTP
  P->>B: POST .../otp/verify
  S->>P: Chọn network, nhập địa chỉ
  P->>B: GET .../withdrawals/fee (preview)
  P->>B: POST /shop/online-balance/withdrawals

Networks hỗ trợ: BTC, ETH, USDT (tùy config).
Giới hạn: GET /shop/portal-withdrawal-limits.
Component: WithdrawOtpStep, WithdrawBlockedAlert từ @kioskgaming/ui.

4. Cashier management

Shop Portal quản lý cashier, không thực hiện giao dịch quầy.

Action	Mô tả
Tạo cashier	Username + password
Suspend	Tạm khóa tài khoản
Terminate	Chấm dứt vĩnh viễn
Xem báo cáo	Theo period: daily/weekly/monthly
Xem shifts	Lịch sử ca làm việc

Chi tiết nghiệp vụ cashier: Cashier Management.

warning

Cashier login trên Shop Portal bị từ chối — portalLogin trả role: 'cashier' sẽ redirect sang Cashier App.

5. Provider fees (`/provider-fees`)

Shop bật/tắt phương thức thanh toán theo:

Provider (ZeroxProcessing, MEID, …)
Operation (deposit, withdrawal, transfer)
Method ID

Hiển thị: gateway fee, system fee, network fee.

6. Fraud detection (`/fraud-indicators`)

Tab Cashier

High redemptions
Cash discrepancies
Outside-shift transactions

Tab Player

PlayerFraudIndicatorsPanel từ @kioskgaming/ui
Chi tiết + profit analysis + resolve

7. Kiosk domain & Marketing (`/kiosk-domain`)

Subdomain

Tạo/sửa subdomain kiosk (vd: myshop.kioskdomain.com).
API: GET/POST/PATCH /shop/kiosk-domain.

Poster quảng cáo

3 template: NeonArcade, GoldPremium, DarkNeon.

Render HTML → export PNG qua html-to-image.
QR code embed subdomain kiosk.

8. Communication

Broadcasts (nhận)

ShopNotificationBell poll mỗi 2 phút.
GET /shop/broadcasts → acknowledge qua POST .../ack.

Broadcasts (gửi) — cần `can_delegate_popups`

POST /shop/broadcasts — gửi notification tới player.

In-app popups

ShopInAppPopupGate — gate toàn app.
Modes: once / sticky_daily.
Shop gửi popup: POST /shop/in-app-popups (cần quyền delegate).

9. Settings & Security (`/settings`)

Setting	API	Ghi chú
Cost rate	Hiển thị từ profile	Do agent đặt, shop chỉ xem
Low balance warning	`PATCH /shop/settings/low-balance-warning`	Threshold tối thiểu $50
2FA login	`PATCH /shop/settings/two-factor`	Email/phone, cần verified trước
Xác minh tài khoản	`send-otp` → `confirm`	`VerifyNowTrigger` trên header

10. Legacy flows

Route	Trạng thái
`/transfer`	Redirect → `/players`
`/transfer/legacy`	Luồng cũ: lookup phone + OTP registration
`/purchase`	Redirect → `/`

Ghi chú triển khai

Port mặc định 3004 — tránh xung đột admin (3000) và agent (3003).
CORS: thêm domain dev vào admin Domains hoặc DISABLE_CORS=true khi dev local.
Payment return: backend redirect về /payment/success|cancelled|error với query transaction_id, status, message.
Zerox methods cache: useSupportedZeroxMethods cache 24h trong localStorage.

1. Quản lý ví Shop​

Credits wallet​

USD online balance​

Mua credits (ShopCreditPurchaseModal)​

2. Quản lý Player​

Danh sách (/players)​

Tạo player​

Chi tiết player (/players/:playerId)​

3. Rút tiền & Phê duyệt​

Player withdrawals (/withdrawals)​

Shop USD withdrawal (/online-transactions)​

4. Cashier management​

5. Provider fees (/provider-fees)​

6. Fraud detection (/fraud-indicators)​

Tab Cashier​

Tab Player​

7. Kiosk domain & Marketing (/kiosk-domain)​

Subdomain​

Poster quảng cáo​

8. Communication​

Broadcasts (nhận)​

Broadcasts (gửi) — cần can_delegate_popups​

In-app popups​

9. Settings & Security (/settings)​

10. Legacy flows​

Ghi chú triển khai​