Validacoes

Sistema de validacoes do template. Controla quais verificacoes o usuario precisa completar antes de navegar ou executar acoes (depositar, sacar, jogar).

Visao geral

Profile API
    │
    ▼
buildValidationSnapshot()     ← monta snapshot do estado do usuario
    │
    ▼
fetchAllValidations()         ← avalia config da marca + snapshot
    │
    ├── force    (forceRequestKyc = true)
    ├── regulatory (showPendingDataFlow = true)
    ├── global   (config.global.active = true)
    └── contexts (casino, sports, deposit, withdraw, ...)
    │
    ▼
hasPending?
    ├── SIM + force/regulatory/global → ValidationBlockerOverlay (bloqueante)
    └── SIM + contexto especifico    → ValidationStepsModal (fechavel)

Dois modos de exibicao

ValidationBlockerOverlay (obrigatorio)

Renderizado pelo DefaultLayout quando allValidations.hasPending = true e pendingType e "force", "regulatory" ou "global".

• Overlay fullscreen com backdrop-blur-md sobre o site
• Anti-tamper: MutationObserver + interval que recarrega a pagina se o overlay for removido ou escondido via DevTools
• Nao pode ser fechado (sem botao X, ESC bloqueado)
• Carousel de steps com estado (concluido/atual/pendente)
• Opcao de sair da conta (logout)

ValidationStepsModal (frequente/contextual)

Aberto programaticamente via useValidationStepsStore quando o usuario tenta executar uma acao protegida (ex: depositar, sacar, jogar casino).

• Modal com backdrop clicavel e botao X
• Mesmo visual (carousel, step header, step content)
• Fecha ao concluir ou ao clicar fora

Arquivos principais

Arquivo	Tipo	Descricao
app/hooks/useValidationRuntimeSync.ts	Hook	Monta o snapshot, computa allValidations e sincroniza com a store
app/store/validationRuntime.ts	Store	Armazena allValidations computado
app/store/validationSteps.ts	Store	Controla abertura do modal de validacoes contextuais
app/store/passwordValidation.ts	Store	Controla abertura do modal de senha
app/store/kyc.ts	Store	Estado do fluxo KYC (modal, step, polling)
app/layouts/DefaultLayout.tsx	Layout	Decide se mostra o ValidationBlockerOverlay
app/components/validation/ValidationBlockerOverlay.tsx	Component	Overlay bloqueante com anti-tamper
app/components/validation/ValidationStepsModal.tsx	Component	Modal de validacoes contextuais
app/components/validation/ValidationStepContent.tsx	Component	Router que renderiza o step correto por modulo
app/components/validation/steps/*.tsx	Components	Um componente por modulo (email, phone, address, etc.)
app/components/validation/steps/useStepUtils.ts	Hook	syncProfile() + gestao de erro/sucesso compartilhados pelos steps
app/components/validation/ui/*.tsx	Components	Primitivos visuais (OTPInput, PrimaryButton, StepCarousel, etc.)
app/services/validation.client.ts	Service	API calls (send email, verify SMS, submit address, etc.)
app/services/userLimits.client.ts	Service	Atualiza limites prudenciais
app/utils/validationModules.ts	Util	filterSupportedAuthValidation()

:::info buildValidationSnapshot vem do core Nao existe app/utils/validationSnapshot.ts nem app/services/authProfile.client.ts no template.

buildValidationSnapshot, fetchAllValidations e o type RawUserSnapshot sao importados de @cactus-agents/validations; o perfil atualizado vem de useAccountsStore / refreshAuthProfile (@cactus-agents/accounts/react), consumidos pelo syncProfile() do useStepUtils.

// app/hooks/useValidationRuntimeSync.ts
import { useAccountsStore } from "@cactus-agents/accounts/react";
import {
  buildValidationSnapshot,
  fetchAllValidations,
  type RawUserSnapshot,
} from "@cactus-agents/validations";

:::

API Routes

Rota	Metodo	Descricao
/api/auth/profile	GET	Retorna profile atualizado
/api/validation/email/send	POST	Envia codigo de verificacao por e-mail
/api/validation/email/verify	POST	Verifica codigo de e-mail
/api/validation/email/change	POST	Altera e-mail antes de verificar
/api/validation/sms/send	POST	Envia codigo SMS
/api/validation/sms/verify	POST	Verifica codigo SMS
/api/validation/sms/change	POST	Altera telefone antes de verificar
/api/validation/address/submit	POST	Salva endereco
/api/validation/docs/submit	POST	Salva documentos (CPF, nascimento, nacionalidades)
/api/validation/full-name/submit	POST	Salva nome completo (modulo full_name)
/api/validation/link-confirm	POST	Confirma validacao aberta por link (user.validate)
/api/validation/terms/accept	POST	Aceita um termo especifico
/api/user/check-password	POST	Valida senha do usuario
/api/user/update-limits	POST	Atualiza limites prudenciais
/api/user/update-address	POST	Atualiza endereco
/api/kyc/start	POST	Inicia verificacao KYC
/api/kyc/status	POST	Consulta status KYC

Steps implementados

Cada modulo tem seu proprio componente em components/validation/steps/:

Modulo	Componente	O que faz
email	EmailStep	Envia codigo, OTP input, alterar e-mail
phone / sms	PhoneStep	Envia SMS, OTP input, alterar telefone + DDI
address	AddressStep	CEP, rua, cidade, estado (select BR), pais
docs / document	DocsStep	CPF, data nascimento, nacionalidades
password	PasswordStep	Input senha com toggle show/hide
user_limits	LimitsStep	Tempo de jogo e limite de perda (ilimitado/personalizado)
kyc	KycStep	Descricao + iniciar verificacao + badge CPF/ID
terms	TermsStep	Toggles individuais por termo + aceitar todos
gps	GpsStep	Solicitar geolocalizacao do navegador
bank_account	BankAccountStep	Aviso + navegar para dados da conta
full_name	FullNameStep	Nome completo (submit via /api/validation/full-name/submit)

Fluxo de resolucao de step

Usuario preenche formulario
    │
    ▼
Step chama API (ex: submitValidationAddress em ~/services/validation.client)
    │
    ▼
Step chama syncProfile() (useStepUtils) → refetch do perfil
    │
    ▼
useAccountsStore atualiza user + userInfo
    │
    ▼
useValidationRuntimeSync recomputa allValidations
    │
    ├── Ainda tem pendencia → proximo modulo aparece
    └── Sem pendencia → overlay/modal desmonta automaticamente

O snapshot e recomputado a partir de useAccountsStore (isAuthenticated, user, userInfo) mais brand.features.authConfig.registerTypeVersion e o featuresConfig — nunca de useRouteLoaderData("routes/_layout"), que nao carrega mais auth.

Theming

Todos os modais de validacao usam as cores auth.* de app/config/theme/colors.ts:

Token	Uso
auth.bg-primary	Fundo do modal
auth.bg-inputs	Fundo dos inputs
auth.text-inputs	Texto dos inputs
auth.button-bg	Fundo dos botoes primarios
auth.button-text	Texto dos botoes primarios
auth.links	Cor de destaque (labels, badges, carousel ativo)
auth.titles	Titulos
auth.texts	Textos secundarios
auth.bg-close	Fundo do botao fechar
auth.icon-close	Icone do botao fechar
auth.backdrop	Fundo do backdrop

Como adicionar um novo modulo

1. Criar o predicado em front-cactus-core/packages/validations/src/modules.ts
2. Adicionar o nome em ValidationModuleName (packages/validations/src/types.ts) e publicar versao nova do pacote
3. Criar o componente app/components/validation/steps/NomeStep.tsx no template
4. Registrar no switch do app/components/validation/ValidationStepContent.tsx
5. Adicionar o label em app/components/validation/constants.ts (getModuleLabels(), consumido por labelForModule())
6. Adicionar o icone em app/components/validation/ui/StepCarousel.tsx (MODULE_ICONS)
7. Se o modulo precisa de endpoint proprio, criar a rota em app/routes/api/validation/ e registrar em app/router/routes.ts