Wallet

Integracao de carteira, bonus, cashback, rollover e historico de transacoes no template via @cactus-agents/wallet.

Arquivos principais

Arquivo	Tipo	Descricao
store/wallet.ts	Store (Zustand)	Saldos, transacoes, rollover, modais
hooks/useWallet.ts	Hook	Estado derivado, formatacao, actions
utils/walletRefresh.client.ts	Util	Refresh automatico de saldo
components/user/wallet/	Components	Cards de saldo, transacoes, modais

Store — useWalletStore

interface WalletState {
  wallet: Wallet | null;              // saldo real, bonus, cashback
  walletLoading: boolean;
  transactions: Transaction[];         // historico
  transactionsMeta: TransactionMeta;   // paginacao (total, currentPage, perPage)
  transactionsLoading: boolean;
  transactionsFilter: TransactionFilter;
  rollover: Rollover | null;           // status do rollover
  walletModal: "bonus-withdraw" | "bonus-rules" | "cashback-redeem" | null;
}

Hook — useWallet()

Estado derivado

Propriedade	Descricao
formatMoney(value)	Formatacao locale-aware (ex: R$ 1.234,56)
walletRealFormatted	Saldo real formatado
walletBonusFormatted	Saldo bonus formatado
walletCashbackFormatted	Saldo cashback formatado
walletHasReal / walletHasBonus / walletHasCashback	Flags (saldo > 0)
walletHasFirstDeposit	Se o usuario ja depositou
rolloverAccomplished	Se o rollover foi cumprido

Actions

Action	Descricao
hydrateFromLoader(data)	Inicializa estado com dados do SSR loader
updateWallet()	Refresh do saldo (via API route)
fetchTransactions(filter?)	Busca transacoes paginadas
transferBonus()	Transfere saldo bonus para real
transferCashback()	Transfere cashback para real

API Routes

Rota	Metodo	Descricao
api/wallet/refresh	POST	Refresh completo (saldo + rollover)
api/wallet/transactions	POST	Transacoes paginadas com filtros
api/wallet/action	POST	Transfer bonus/cashback
api/wallet/receipt	POST	Gera comprovante de saque

Paginas

Rota	Descricao
/user/wallet	Pagina principal: cards de saldo + rollover
/user/wallet/transactions	Historico de transacoes com filtros e paginacao

Componentes

Cards de saldo

• RealWalletCard — saldo real com botao de deposito
• BonusWalletCard — saldo bonus + progresso do rollover
• CashbackWalletCard — saldo cashback com botao de resgate

Transacoes

• TransactionTable — tabela de transacoes com status coloridos
• TransactionTabs — tabs de tipo (deposito, saque, bonus, cashback)
• TransactionPeriods — filtro por periodo
• Pagination — navegacao de paginas

Modais

• BonusWithdrawModal — confirmacao de transferencia bonus → real
• BonusRulesModal — regras do bonus ativo
• CashbackRedeemModal — confirmacao de resgate de cashback
• WithdrawDetailsModal — comprovante de saque

Outros

• WalletInitializer — componente montado no layout que atualiza o saldo automaticamente apos login
• CountdownTimer — timer regressivo (ex: expiracao de bonus)
• ProgressBar — barra de progresso do rollover