KIOSK-254 — Pages to Apply USD Wallet Wording Changes

Field	Value
Task ID	KIOSK-254
Mục tiêu	Đồng bộ tên giao dịch USD Wallet và nhãn tài chính trên 3 portal vận hành
In scope	kioskgaming_admin, kioskgaming_superagent, kioskgaming_agent, shared UI packages/ui (portal-usd-wallet, portal-ledger)
Out of scope (v1)	Shop portal (kioskgaming_shop), đổi route URL (/online-transactions), đổi tên biến/API nội bộ (onlineBalanceNet, fetchAgentOnlineBalanceLedger), DB schema
Related	Finance System · Admin USD wallet detail view · Task-kiosk-260 (correction / reversal / refund labels trên Admin)

---

1. Background

Trong codebase, USD Wallet (usd_wallets + usd_wallet_transactions) là ví tiền thật (USD) dùng để mua credit, nhận settlement deposit, và rút crypto. Tuy nhiên UI vẫn còn nhiều tên legacy:

Thuật ngữ legacy	Vấn đề
Online balance	Không khớp tên sản phẩm; user không biết đây là “USD Wallet”
Online transactions (nav Agent)	Khác với Super Agent / page title (“USD wallet transactions”)
Online balance top up / withdrawal (Shop utils)	Chỉ Shop — out of scope KIOSK-254 nhưng cùng pattern cần tránh lan sang portal in-scope

Mục tiêu ticket: một bộ từ vựng thống nhất — ưu tiên “USD wallet” / “USD Wallet” cho tên sản phẩm và mô tả số dư; transaction labels dùng chung từ @kioskgaming/ui khi có thể.

---

2. Quy ước wording (source of truth)

2.1 Tên sản phẩm & số dư

Ngữ cảnh	Label chuẩn (EN)	Không dùng
Tên ví / sidebar / dashboard card	USD wallet	Online balance, online USD balance
Số dư khả dụng	Current USD balance hoặc USD wallet balance	Online balance, USD online balance
Trang ledger chính	USD wallet transactions	Online transactions
Mô tả trang	Track USD wallet ledger activity, balances, and withdrawal requests.	Online balance ledger…
Rút tiền	Request withdrawal / USD withdrawal	Online balance withdrawal
Mua credit từ USD	Convert USD wallet balance to credits / USD converted to credits	Convert online balance…

Capitalization: Nav / page title → sentence case (USD wallet transactions). Badge / card heading ngắn → USD wallet. Modal title có thể USD Wallet khi là proper noun (timeline step).

2.2 Nhãn loại giao dịch (ledger table & detail)

Dùng chung từ packages/ui/src/portal-usd-wallet/ledgerUtils.ts (usdLedgerTypeLabel) và portal-ledger/usdTransactionPresentation.ts (buildUsdBusinessView):

Signal (type / ref)	Label list / table	Detail modal title
deposit	Deposit	USD added to wallet
withdrawal (payout)	Withdraw	USD withdrawal
purchase_credits / balance_to_credits	Purchase credits	USD converted to credits
adjustment credit	Balance Correction — Credit	Wallet adjustment
adjustment debit	Balance Correction — Debit	Wallet adjustment
reversal	Transaction Reversal	Wallet activity reversed
Refund flows	Refund	(Admin: displayLabel từ API — xem KIOSK-260)
Fallback	USD wallet activity	USD wallet activity

Admin list/detail: ưu tiên displayLabel / displayCategory từ API (usdLedgerEnrichment) khi có — không duplicate heuristic ở frontend. Xem Task-kiosk-260.

2.3 Status labels (giữ nguyên — đã thống nhất)

Completed · Pending · Processing · Failed · Cancelled — từ usdLedgerStatusLabel.

---

3. Scope — bảng thay đổi theo portal

3.1 Admin Portal (kioskgaming_admin)

Page / Area	Route / file	Hiện tại (gap)	Required change
Nav / route meta	/usd-wallets · routes.tsx	Title nav: USD Wallets	Giữ hoặc đổi thành USD wallet transactions nếu product muốn khớp portal khác; breadcrumb thống nhất
USD wallet ledger	usdWallets/index.tsx	Title đã là USD wallet transactions ✅	Rà soát toast/export: USD ledger exported → có thể USD wallet ledger exported
Ledger detail modal	UsdWalletLedgerDetailModal.tsx · UsdWalletActivityView.tsx	Một số câu dùng “online balance”, “online USD”	Đổi sang USD wallet / USD wallet balance (xem §3.1 copy table)
Agent detail — balance card	agents/AgentDetailPage.tsx	USD wallet ✅	Giữ; sublabel Gross net giữ nguyên
Super Agent detail	superAgents/SuperAgentDetailPage.tsx	USD wallet balance ✅	Giữ
Shop detail	agents/ShopDetailPage.tsx	USD wallet ✅	Giữ
Finance correction modal	finance/FinanceCorrectionDebitModal.tsx	USD online balance, USD (online balance)	→ USD wallet balance / USD wallet
Super Agent withdrawal limits	SuperAgentPortalWithdrawalLimitsCard.tsx	Online balance withdrawal limits (USD)	→ USD wallet withdrawal limits
Payment transaction detail	transactions/TransactionDetails.tsx	paid online USD balance	→ paid from USD wallet / used USD wallet balance
Cash flow timeline	utils/transactionCashFlowTimeline.ts	USD Wallet, USD wallet movement ✅	Giữ; đảm bảo leg labels khớp buildUsdBusinessView
Credit wallet cross-ref	CreditWalletActivityView.tsx	USD wallet transaction ✅	Giữ
Provider fees table	providerFees/providerFeesColumns.tsx	USD wallet · internal transfer ✅	Giữ

Admin activity copy — thay thế cụ thể (UsdWalletActivityView.tsx):

Pattern cũ	Pattern mới
converted online balance to	converted USD wallet balance to
used online USD to buy	used USD wallet balance to buy
(các câu đã có “USD wallet”)	Giữ

---

3.2 Super Agent Portal (kioskgaming_superagent)

Page / Area	Route / file	Hiện tại (gap)	Required change
Sidebar nav	AppLayout.tsx · /online-transactions	USD wallet transactions ✅	Giữ
Breadcrumb	superAgentBreadcrumb.ts	USD wallet transactions ✅	Giữ
Ledger page	OnlineBalanceTransactionsPage.tsx	Page title USD wallet transactions ✅	Rà toast: Could not load online balance ledger trong hook → USD wallet ledger
Dashboard	DashboardPage.tsx	Card USD wallet + link USD wallet transactions ✅	Giữ
Sidebar balance	AppLayout.tsx	Current USD balance ✅	Có thể đổi thành USD wallet balance nếu muốn khớp Admin Super Agent detail
Credit purchase	CreditPurchaseModal.tsx · CreditPurchaseTrigger.tsx	online USD balance, Insufficient online balance, Use online USD balance	→ USD wallet balance / Insufficient USD wallet balance
Managed shop wallet	ManagedShopWalletHistoryPanel.tsx	Tab label USD wallet, empty No USD wallet transactions yet ✅	Giữ
Credit / USD tx list	AgentTransactionsPage.tsx	Dùng UsdWalletTransactionDetailModal từ UI package	Labels từ shared package (§4)
Provider fees	providerFees/MethodCell.tsx	USD wallet · internal transfer ✅	Giữ
Hooks / errors	useSuperAgentOnlineBalanceLedger.ts	Could not load online balance ledger	→ Could not load USD wallet ledger

---

3.3 Agent Portal (kioskgaming_agent)

Page / Area	Route / file	Hiện tại (gap)	Required change
Sidebar nav	AppLayout.tsx · /online-transactions	Online transactions ❌	→ USD wallet transactions (khớp Super Agent + page title)
Ledger page	OnlineBalanceTransactionsPage.tsx	Title USD wallet transactions ✅	Đồng bộ nav (trên)
Sidebar balance	AppLayout.tsx	Current USD balance ✅	Tùy chọn: USD wallet balance
Shop detail — tab	ShopDetailPageRedesign.tsx	Tab USD wallet tx	→ USD wallet transactions (hoặc USD wallet nếu thiếu chỗ)
Shop detail — section	ShopDetailPageRedesign.tsx	Subtitle Online balance (USD wallet) ledger entries	→ USD wallet ledger entries
Shop detail — empty/loading	ShopDetailPageRedesign.tsx	Loading USD transactions…, No USD transactions yet	→ USD wallet transactions
Credit purchase	CreditPurchaseModal.tsx · CreditPurchaseTrigger.tsx	Giống Super Agent — online balance	→ USD wallet balance
Provider fees	providerFees/MethodCell.tsx	USD wallet · internal transfer ✅	Giữ
Hooks / errors	useAgentOnlineBalanceLedger.ts	Could not load online balance ledger	→ Could not load USD wallet ledger

---

4. Shared UI package (packages/ui)

Agent + Super Agent (+ phần list Admin) dùng chung module này. Sửa một lần → cả 3 portal hưởng lợi (trừ Admin detail riêng).

Module	File chính	Wording cần rà
portal-usd-wallet	ledgerUtils.ts	usdLedgerTypeLabel, usdPartyDisplayLabel, summary grid
	PortalUsdWalletSummaryGrid.tsx	Current USD balance, Available for withdrawal ✅
	PortalUsdWalletLedgerTable.tsx	Column headers: Owner, Type, Status, Balance before/after (net)…
	PortalWithdrawalLimitsPanel.tsx	Withdrawal limit copy
portal-ledger	usdTransactionPresentation.ts	Nhiều chỗ online USD balance / online balance → đổi sang USD wallet (balance)
	UsdWalletTransactionDetailModal.tsx	Tiêu đề từ buildUsdBusinessView
	cashFlowTimelineSample.ts	Sample Online balance → USD wallet

4.1 usdTransactionPresentation.ts — copy đích

Field	Hiện tại	Đổi thành
summaryLine (B2C)	…from your online balance into credits	…from your USD wallet into credits
subtitle (deposit)	Your online USD balance increased	Your USD wallet balance increased
subtitle (withdrawal)	…from your online USD balance	…from your USD wallet
subtitle (generic)	…affected your online USD balance	…affected your USD wallet balance
balanceRows label	Total debited from USD Wallet	Giữ (đã đúng)

---

5. Kiến trúc triển khai

┌─────────────────────────────────────────────────────────────┐
│  packages/ui                                                 │
│  portal-usd-wallet/ledgerUtils.ts                           │
│  portal-ledger/usdTransactionPresentation.ts                │
└───────────────────────────┬─────────────────────────────────┘
                            │ import @kioskgaming/ui
        ┌───────────────────┼───────────────────┐
        ▼                   ▼                   ▼
   kioskgaming_agent   kioskgaming_superagent   kioskgaming_admin
   (nav, hooks,        (hooks, credit           (usdWalletLedgerUtils,
    shop detail,         purchase copy)           ActivityView, finance modal)
    credit purchase)

Thứ tự đề xuất:

1. UI package — transaction detail + type labels (K254-UI-1)
2. Agent + Super Agent — nav, hooks, credit purchase, shop detail (K254-AG-1, K254-SA-1)
3. Admin — chỗ còn “online balance” + finance/super-agent cards (K254-AD-1)
4. QC grep — không còn user-facing online balance trên 3 app in-scope (K254-QC-1)

Không đổi trong task này: tên hook useAgentOnlineBalanceLedger, endpoint online-balance, field API online_balance_net — chỉ đổi string hiển thị.

---

6. Implementation plan (reviewable tasks)

ID	Task	Repo	Size
K254-UI-1	Replace online balance / online USD strings trong usdTransactionPresentation.ts + tests	packages/ui	S
K254-UI-2	Rà ledgerUtils.ts + PortalUsdWalletSummaryGrid (nếu cần USD wallet balance label)	packages/ui	XS
K254-SA-1	Super Agent: credit purchase copy + hook error toast	kioskgaming_superagent	XS
K254-AG-1	Agent: nav label, shop detail subtitles, credit purchase, hook toast	kioskgaming_agent	S
K254-AD-1	Admin: UsdWalletActivityView, FinanceCorrectionDebitModal, SuperAgentPortalWithdrawalLimitsCard, TransactionDetails	kioskgaming_admin	S
K254-QC-1	Grep gate + checklist QC (§7)	all	XS

Phụ thuộc KIOSK-260: Admin badge Refund / Balance Correction do API displayLabel — K254 không thay logic classification; chỉ đảm bảo narrative text dùng “USD wallet” thay “online balance”.

---

7. Test plan (QC)

7.1 Agent — nav consistency

1. Login Agent portal.
2. Sidebar mục /online-transactions hiển thị USD wallet transactions (không còn “Online transactions”).
3. Page header cùng wording.

7.2 Shared detail modal

1. Mở một row Purchase credits trên Agent hoặc Super Agent.
2. Modal: title USD converted to credits; body không chứa “online balance”.

7.3 Withdrawal flow copy

1. Mở Request withdrawal modal.
2. Label Current USD balance / validation message dùng USD wallet terminology.

7.4 Admin finance correction

1. Mở finance correction debit modal, chọn wallet USD.
2. Không còn option label USD (online balance).

7.5 Shop detail (Agent)

1. Agent → Shop detail → tab USD.
2. Subtitle USD wallet ledger entries; empty state No USD wallet transactions yet.

7.6 Regression grep (automatable)

# User-facing strings — expect 0 matches in src/ (allow comments & API field names)
rg -i 'online balance' kioskgaming_admin/src kioskgaming_agent/src kioskgaming_superagent/src packages/ui/src \
  --glob '!**/*.test.*'

Cho phép ngoại lệ: code comments, tên biến onlineBalanceNet, JSDoc @param onlineBalance.

---

8. Acceptance criteria

• AC-1: Ba portal dùng cùng tên trang USD wallet transactions cho ledger chính (nav + header).
• AC-2: Không còn user-facing “online balance” / “online transactions” (Agent nav) trên in-scope surfaces.
• AC-3: Detail modal & shared ledger labels dùng USD wallet (balance) thay legacy online wording.
• AC-4: Admin entity cards (agent / super agent / shop) vẫn hiển thị USD wallet balance — không regression.
• AC-5: Transaction type labels thống nhất giữa list table và detail modal (shared package).

---

9. File index (quick lookup)

Portal	Files
Shared	packages/ui/src/portal-usd-wallet/ledgerUtils.ts, PortalUsdWalletSummaryGrid.tsx, packages/ui/src/portal-ledger/usdTransactionPresentation.ts
Admin	usdWallets/index.tsx, UsdWalletActivityView.tsx, usdWalletLedgerUtils.ts, finance/FinanceCorrectionDebitModal.tsx, superAgents/SuperAgentPortalWithdrawalLimitsCard.tsx, transactions/TransactionDetails.tsx, agents/*DetailPage.tsx, agents/ShopDetailPage.tsx
Super Agent	pages/OnlineBalanceTransactionsPage.tsx, components/layout/AppLayout.tsx, components/credits/CreditPurchase*.tsx, hooks/useSuperAgentOnlineBalanceLedger.ts, components/shops/ManagedShopWalletHistoryPanel.tsx
Agent	pages/OnlineBalanceTransactionsPage.tsx, pages/ShopDetailPageRedesign.tsx, components/layout/AppLayout.tsx, components/credits/CreditPurchase*.tsx, hooks/useAgentOnlineBalanceLedger.ts

---

10. Definition of done

• Tất cả AC (§8) pass trên staging.
• packages/ui build + Agent/Super Agent/Admin consume bản UI mới.
• Grep gate §7.6 pass (với allowlist documented).
• PR description link doc này + note overlap với KIOSK-260 nếu cùng release.

---

11. Ghi chú cho PM / copywriter

Nếu Jira KIOSK-254 có bảng Required change chi tiết hơn (từng scenario deposit/settlement/payout), bổ sung vào §3 dưới dạng row mới — doc này map từ inventory codebase khi ticket image không đọc được chi tiết.

Các label Balance Correction / Transaction Reversal / Refund thuộc KIOSK-260; KIOSK-254 chỉ cover tên sản phẩm USD Wallet và online → USD wallet narrative, không thay taxonomy correction.