Detentores de tokens

Pré-requisitos de acesso

• Permissão (módulo): manageToken
• Licença/Feature: Nenhuma
• Contêiner do menu: GERAL → grupo Usuários

O que é / quando usar

Tela de consulta que lista quem detém saldo de um token específico e quanto cada cliente possui. O operador escolhe um token na caixa de seleção e a tela retorna, para esse token, o saldo de cada carteira (com o e-mail do titular). Use para auditoria de distribuição de um token, conferência de circulação, levantamento de holders para um evento (snapshot, distribuição) ou simplesmente para investigar a posição de um ativo na base.

É uma tela somente-leitura: não credita, debita nem move saldo. Para operar sobre o saldo de um cliente, use as ações em Detalhes do usuário.

Pré-condições

• Permissão: manageToken cadastrado para a role do operador (gating do item de menu). Permissão é dupla — enum estático CPM + módulo dinâmico no DB; ambos precisam estar associados à role para a tela aparecer. No API-Gateway, o endpoint de saldos por unidade (readAllForUnit) é validado por viewGeneralJournal — garanta que a role do operador também o tenha para que a consulta não retorne erro.
• Licença/Feature: nenhuma.
• Dependências de outras telas: o token precisa existir (cadastrado em Tokenização → Gerenciar Tokens) para aparecer na caixa de seleção.

Passo a passo

1. Acesse o menu Usuários → Detentores de tokens (/manage-owners).
2. Na caixa de seleção, escolha o token cujos detentores você quer consultar.
3. A tabela carrega automaticamente os detentores com e-mail e saldo.
4. Clique no ícone de visualizar (olho) em uma linha para abrir os Detalhes do usuário daquele detentor.
5. Opcional: clique em Exportar para baixar a lista de detentores do token em CSV.

Filtros e colunas

Filtro / Coluna	O que mostra	Origem do dado
Seleção de token	Lista todos os tokens cadastrados; ao mudar, dispara a busca (search)	getTokens (TokenController / obs-lib)
Coluna E-mail (Nome)	E-mail do titular da carteira detentora	Cruzamento customerId → user.email (lista de usuários carregada no initData)
Coluna Valor (Saldo)	Saldo do token naquela carteira, exibido com 2–8 casas	balance de cada AccountBalance retornado por readAllForUnit(unitOfMoney) (FinLib) — considera apenas movimentos de carteira (CREDIT/DEBIT)
Ação Visualizar	Abre os Detalhes do usuário do detentor	Navega para /users/informations/details?userEmail=...

Ações e modais

• Selecionar token: trocar o token na caixa de seleção re-executa a consulta readAllForUnit para a nova unidade.
• Exportar (CSV): gera um CSV no navegador com as colunas name (e-mail) e amount (saldo) dos detentores listados. O arquivo é montado no front (não há chamada extra ao backend) e nomeado transactions_<data>.csv.
• Visualizar (olho): abre os Detalhes do usuário do detentor, onde estão as ações administrativas individuais.

Regras de negócio / cuidados

Atenção

• Saldo ≠ disponível para saque. O número exibido é o saldo contábil da carteira para aquele token. Travas como carteira em captação (status de captação do captador), holds ou ordens em aberto não são descontadas nesta visão — um detentor pode aparecer com saldo aqui e ainda assim estar bloqueado para saque/transferência. Para o estado operacional do cliente, confira os Detalhes do usuário.
• A lista depende do cruzamento com a base de usuários. O e-mail vem do casamento customerId → usuário; carteiras técnicas/de sistema (ex.: owner do token, sinks) podem aparecer sem e-mail legível.

• Valores financeiros: os saldos vêm da FinLib e são tratados com precisão (BigNumber) — a UI apenas formata para 2–8 casas na exibição. Para conferência exata, use o saldo bruto (export/CSV) e respeite as casas decimais do token.

Telas relacionadas

• Detalhes do usuário — ações administrativas sobre o saldo de um detentor.
• Gerenciar Tokens — onde os tokens listados na seleção são cadastrados.
• Saldos (Dashboard) — visão agregada de saldos da plataforma.