Detalhes do usuário — Geral
Pré-requisitos de acesso
- Permissão (módulo):
viewUser(abrir a tela). Cada ação dentro dela exige um módulo próprio — ver a tabela de ações. - Licença/Feature: Nenhuma para abrir. Algumas abas/ações dependem de features:
USER_KYC/CROWDFUNDING(Documentos),BACKOFFICE_DIGITAL_BANKING/DIGITAL_BANKING(Conta Digital),MANAGE_NFTS(NFTs/Buy-Track),STAKING_PERMISSION(Staking),ADMIN_BALANCE_CONTROL(crédito/débito/stake manual). - Contêiner do menu: GERAL → grupo Usuários (acessada pelo olho na Lista de usuários)
O que é / quando usar
É a visão 360 de um único cliente e o centro das operações administrativas individuais. Reúne dados cadastrais, carteiras on-chain, saldos (cripto + NFTs + banco digital), histórico de transações, staking, ordens, jornais blockchain, log antifraude, solicitações de saque, histórico de acesso e logs de e-mail — além das ações administrativas (confirmar conta, desabilitar, resetar MFA, forçar logout, trocar e-mail, creditar/debitar saldo, alocar manualmente etc.). Use sempre que precisar investigar, dar suporte ou operar manualmente sobre um cliente específico.
A tela é alimentada por vários microsserviços (CPM, KYC, BSM/BankManagement, Staking, OrderBook/OBS, AuditService, NotificationService) agregados pelo AccountService e serviços auxiliares.
Pré-condições
- Permissão:
viewUserpara abrir. Cada ação tem seu módulo (ver tabela). Permissão é dupla: enum CPM no backend + módulo dinâmico no DB — sem o módulo associado à role, o botão nem aparece (gating por diretiva*appHasPermission). - Licença/Feature: abas se ativam conforme as features do tenant; ações de saldo manual exigem
ADMIN_BALANCE_CONTROL. - Dependências: para operar financeiramente em nome do cliente, ele precisa estar
status === 'APPROVED'.
Estrutura da tela — abas (seções)
| Aba | O que mostra | Condição para aparecer |
|---|---|---|
| Geral | Dados cadastrais, carteiras (EVM/BTC/TRON/XRP), saldos, gráficos, cards de ação, comissões agente/parceiro, indicados/responsáveis | Sempre |
| Adicionais | Informações e endereços adicionais do cadastro | Só se houver dados adicionais |
| Histórico | Sub-abas: Transações, Staking, Conta Digital | Sempre (Conta Digital só com banco digital) |
| Extratos especiais | Sub-abas: Compras de NFT (Buy-Track), NFTs do cliente, Ordens, Sincronismos blockchain, Saques blockchain, Log antifraude, Solicitações de saque, Histórico de acesso, Logs de e-mail | Sempre (Buy-Track/NFTs só com MANAGE_NFTS) |
| Documentos | Documentos de KYC (carteira e banco) com status | Só com KYC configurado (USER_KYC ou CROWDFUNDING) |
| Conta Digital | Dados bancários, chaves PIX, extrato e ações da conta | Só com banco digital configurado |
| Identidade on-chain | Identidade regulada (ERC-3643) do usuário | Sempre (gate de feature pendente — ver nota) |
| Informe de Rendimentos (IR) | Dados de IRPF | Sempre (desabilitada se vazia) |
Aba "Identidade on-chain"
Atualmente é sempre exibida porque ainda não existe uma feature flag dedicada (futuro REGULATED_TOKENIZATION/ERC-3643). Quando a flag existir, a aba passará a ser condicional. Trate-a como informativa enquanto a tokenização regulada não estiver ativa no tenant.
Ações administrativas (card "Ações" + card de saldo)
Cada botão só aparece se o módulo correspondente estiver na role do operador. Várias dessas rotas exigem step-up (re-autenticação senha+MFA, header X-Step-Up-Token) e/ou um código MFA do app autenticador (modal de código) antes de executar.
| Ação | O que faz / efeito no backend | Permissão | Confirmação / step-up |
|---|---|---|---|
| Resetar MFA | Limpa o segundo fator do usuário para que ele reconfigure | resetUserMfa | Código MFA do admin (Authy) |
| Forçar logout | Encerra todas as sessões ativas do usuário | forceLogout | Bottom-sheet de confirmação |
| Confirmar conta | Aprova o cadastro (status → APPROVED) via CPM | approveKycCpm | Confirmação + código MFA; rota com step-up |
| Desabilitar usuário | Bloqueia o usuário e redireciona para a lista | disableUser | Confirmação + código MFA; rota com step-up |
| Alterar perfil | Abre edição de perfil (agente/parceiro etc.) | manageLimits | Modal |
| Editar perfil (dados) | Edita dados cadastrais do usuário | editUserProfile | Modal |
| Atualizar documentos | Abre upload de documentos pessoais de KYC | uploadKycCpm | Modal de documentos |
| Enviar documento (genérico) | Upload de documento genérico (ex.: evidência) | uploadKycCpm | Modal |
| Alterar e-mail | Troca o e-mail de login | alterEmail | Modal + código MFA |
| Criar conta digital | Inicia onboarding bancário pelo BackOffice | manageBankingAccount | Só aparece se banco digital ativo e usuário sem conta |
| Creditar saldo | Crédito manual no saldo cripto do usuário | sendBalance (+ ADMIN_BALANCE_CONTROL) | Modal de transferência |
| Debitar saldo | Débito manual no saldo cripto do usuário | sendBalance (+ ADMIN_BALANCE_CONTROL) | Modal de transferência |
| Adicionar ao stake | Aporta saldo do usuário em staking | sendBalance (+ ADMIN_BALANCE_CONTROL) | Modal de staking |
| Alocação manual | Aloca o usuário em crowdfunding/token/NFT debitando o saldo cripto dele | manualUserAllocation | Wizard 3 passos + evidência obrigatória; rota com step-up |
| Tokens do usuário | Gerencia tokens/posições do usuário | manualUserAllocation | Modal |
| Transferir NFT | Transfere uma NFT do usuário | manualUserAllocation (no card) | Modal por NFT |
| Ver chave privada | Revela a chave privada (EVM/BTC) | getPrivateWallet | Modal de confirmação |
| Permitir staking | Habilita o usuário a fazer staking | — | Confirmação |
Comissões de agente/parceiro
Quando o usuário é agente e/ou parceiro, o card Comissões permite editar o percentual de comissão e o toggle Pagar no final (paid_at_end). Os valores são percentuais (0–100, validados) e gravam no profile do usuário.
Ajuda contextual
O ícone de informação no cabeçalho abre o modal de troubleshooting (helpGuide.usersDetails) — um guia in-app estruturado para esta tela.
Regras de negócio / cuidados
Atenção
- Status do usuário ≠ status da conta digital. Confirmar a conta (
approveKycCpm) muda ostatusdo cadastro; não cria nem aprova a conta bancária. - O status da conta digital e o saldo do banco digital são lidos do BLS, não do provider. Divergências podem indicar conta órfã no provider (ver Auditoria → Falhas na criação de Banco Digital).
- A carteira em captação (
walletStatus = IN_CAPTATION) trava saque/transferência do usuário — é o estado de captador. Alterar o status da carteira é uma ação consciente (modalSelectWalletStatus). - Saldos só listam tokens com saldo > 0 e ocultam
USDinterno; o saldo do Banco Digital é injetado à parte.
Irreversível
- Crédito/Débito manual de saldo e Alocação manual movimentam dinheiro real do usuário. Não há rollback automático — confira valor, token e destino antes de confirmar.
- Desabilitar usuário bloqueia o acesso imediatamente.
- Valores financeiros: todos tratados como BigNumber (sem arredondamento) — confira as casas decimais do token antes de creditar/debitar.
- Idempotência: operações financeiras em nome do usuário usam
externalIdestável (ex.:manual-alloc-<orderId>). Se o FinLib retornarE00021"already processed", a operação já foi efetivada — trate como sucesso, não repita. - Status APPROVED: crédito/débito, stake manual e alocação manual exigem o usuário-alvo
APPROVED. A alocação manual ainda exige upload de evidência (ADMIN_ALLOCATION_EVIDENCE) antes do submit e grava o aceite de termos em nome do usuário, com marcador de admin.
Exemplos
Cenário 1 — Confirmar manualmente um cadastro pendente
- Localize o cliente na Lista (filtro Status =
PENDING) e abra os Detalhes. - Verifique os documentos na aba Documentos (status do KYC).
- No card Ações, clique em Confirmar conta (visível só com
approveKycCpm). - Confirme no bottom-sheet e informe o código MFA do seu autenticador (a rota usa step-up).
- Resultado:
user.statuspassa aAPPROVEDno CPM; o cliente passa a poder operar e receber operações em seu nome.
Cenário 2 — Crédito manual de saldo cripto (atendimento com contrato offline)
- Confirme que o usuário está
APPROVED. - No card de saldo (visível com
sendBalance+ADMIN_BALANCE_CONTROL), clique em Creditar. - Escolha o token e o valor (tratado como BigNumber).
- Confirme. Se a chamada ao FinLib retornar
E00021"already processed" num retry, considere efetivado — o valor já entrou. - Confira o lançamento na aba Histórico → Transações (entrada CREDIT).
Cenário 3 — Alocação manual em crowdfunding em nome do cliente
- Abra os Detalhes do cliente (
APPROVED). - No card Alocação manual (módulo
manualUserAllocation), clique em Abrir. - Passo 1: escolha o tipo Crowdfunding. Passo 2: selecione o projeto e o valor (respeitando o aporte mínimo). Passo 3: escolha a cripto de pagamento do saldo do próprio usuário.
- Faça o upload da evidência (documento do pedido offline) — obrigatório.
- Confirme (rota com step-up). O sistema debita o saldo cripto do usuário, grava o aceite de termos em nome dele com marcador de admin + referência do documento, e registra a alocação. O mint dos ativos do crowdfunding permanece exclusivo do job de crowdfunding — esta ação não emite NFT.