Tính năng nghiệp vụ

---

1. Quản lý ví Agent

Credits wallet

• Số dư chính (credit_balance) hiển thị trên sidebar và dashboard.
• Dùng để mua credit và phân phối xuống shop.

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 (CreditPurchaseModal)

Hai phương thức:

Phương thức	Luồng
Crypto	Ví tĩnh ZeroxProcessing (BTC, DOGE, LTC…), QR code
Balance	Chuyển USD → credits theo cost_rate

flowchart LR
  A[Agent mở modal mua credit] --> B{Chọn phương thức}
  B -->|Crypto| C[Chọn coin → QR ví tĩnh]
  B -->|Balance| D[Nhập USD → preview credits]
  D --> E[POST /agent/convert-balance-to-credits]
  C --> F[Agent gửi crypto → backend callback]

Phân phối & rút credit

Action	API	Mô tả
Phân phối xuống shop	POST /agent/credits/distribute	Agent → Shop
Rút từ shop về agent	POST /agent/shops/:id/credits/withdraw	Shop → Agent

---

2. Quản lý Shops

Danh sách (/shops)

• Xem tất cả shops thuộc agent.
• Tạo shop: name, username, email, phone, password, cost_rate (phải > agent cost rate).
• Suspend / Unsuspend qua ShopGovernanceModal.

Chi tiết shop (/shops/:shopId)

Tab Overview

• Thông tin shop, credit balance, USD balance.
• Actions: phân phối credit, rút credit từ shop.

Tab Security

Action	API
Đổi tên	PATCH /agent/shops/:id/name
Đổi password	PATCH /agent/shops/:id/password
Cập nhật cost rate	PATCH /agent/shops/:id/cost
Popup permission	PATCH /agent/shops/:id/popup-permissions

Tab Credit / USD transactions

• Ledger riêng cho từng shop.
• Modal chi tiết giao dịch.

Tab Games

• Bật/tắt game providers cho shop.
• GET/PUT /agent/shops/:id/game-mappings.

Hierarchy stats (AgentHierarchyMiniTree)

• Thống kê deposit/withdrawal/users theo shop trong khoảng ngày.
• API: GET /agent/shops/stats?from=...&to=....

---

3. Quản lý Players

Danh sách (/players)

• Tất cả players thuộc shops của agent.
• Filter client-side: shop, username, phone, email.

Chi tiết (/players/:playerId)

AgentPlayerDetailPanel hiển thị:

• Profile, balance, shop liên kết.
• Lịch sử wallet transactions (GET /agent/players/:id/transactions).

note

Agent không deposit/redeem credits trực tiếp cho player — thao tác này thuộc Shop Portal.

---

4. Giao dịch Credit (/transactions)

• Dùng PortalCreditTransactionsLedger từ @kioskgaming/ui.
• Filter: period, type, search; pagination; export CSV.
• Modal chi tiết credit transaction.

---

5. Rút tiền USD (/online-transactions)

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

sequenceDiagram
  participant A as Agent
  participant P as Agent Portal
  participant B as Backend

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

• Networks: BTC, ETH, USDT (ERC/TRC tùy config).
• Giới hạn: GET /agent/portal-withdrawal-limits.
• Yêu cầu tài khoản đã verify email/phone.

---

6. Provider Fees (/provider-fees)

• Read-only — agent chỉ xem, không chỉnh sửa.
• Hiển thị phí theo provider/operation/methodId.
• Gateway fee, system fee, network fee.

---

7. Fraud Indicators (/fraud-indicators)

• PlayerFraudIndicatorsPanel từ @kioskgaming/ui.
• Filter theo shop.
• Chi tiết indicator + profit analysis withdrawal.
• Resolve indicator với ghi chú.

---

8. Communication

Broadcasts (nhận)

• AgentNotificationBell poll mỗi 2 phút.
• GET /agent/broadcasts → acknowledge qua POST .../ack.

Broadcasts & Popups (gửi) — cần can_delegate_popups

Loại	Route	API
Broadcast	/broadcasts/send	POST /agent/broadcasts
In-app popup	/popups/send	POST /agent/in-app-popups

Popup modes: once / sticky_daily.

---

9. Settings & Security (/settings)

Setting	API	Ghi chú
Cost rate	Hiển thị từ profile	Read-only — do super agent/admin đặt
Low balance warning	PATCH /agent/settings/low-balance-warning	Threshold tối thiểu $50
2FA login	PATCH /agent/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. So sánh Agent vs Shop Portal

Tính năng	Agent Portal	Shop Portal
Quản lý shop	✅ Tạo, suspend, cost rate	—
Quản lý player	✅ Xem (read-only actions)	✅ Tạo, deposit, ban
Phân phối credit	✅ Agent → Shop	—
Mua credits	✅	✅
Rút USD crypto	✅	✅
Duyệt player withdrawal	—	✅
Quản lý cashier	—	✅
Kiosk domain	—	✅
Provider fees	Read-only	Có thể chỉnh sửa
Game mappings	✅ Per shop	—

---

Ghi chú triển khai

1. Port mặc định 3003 — tránh xung đột admin (3000) và shop (3004).
2. CORS: thêm localhost:3003 vào admin Domains hoặc DISABLE_CORS=true khi dev local.
3. Payment return: backend redirect về /payment/success|cancelled|error.
4. Cost rate shop: phải lớn hơn agent cost rate khi tạo/cập nhật shop.
5. Zerox methods cache: useSupportedZeroxMethods cache 24h trong localStorage.