Gestão de Usuários

Resumo

Módulo central para gerenciar todas as pessoas que acessam a plataforma: administradores, afiliados, clientes finais e usuários sem empresa. Inclui criação, edição, bloqueio, reset de senha, impersonação, gestão de sessões, permissões granulares por papel (RBAC), ajuste de saldo em carteira e controle de preferências.

Para quem é (papel/role)

• super-admin - vê e edita todos os usuários de todos os tenants.
• tenant-admin - vê e edita apenas usuários do próprio tenant (isolamento por tenant_id).
• platform-staff - acesso somente leitura para suporte, conforme role concedido.

O que você pode fazer

Cadastro e edição

• Criar usuário: cadastro manual com e-mail, senha inicial, role e tenant/empresa opcional.
• Editar dados: nome, e-mail, telefone, foto, metadados.
• Excluir usuário: remoção lógica respeitando retenção LGPD.
• Listar com filtros: busca por nome, e-mail, tenant, empresa, role, status, data.

Segurança e acesso

• Bloquear / desbloquear: suspende login sem apagar a conta.
• Reset de senha: gera senha temporária ou dispara e-mail com link.
• Revogar sessões: invalida todas as sessões ativas do usuário ou uma sessão específica.
• Impersonar: assume a sessão do usuário em modo "logado como" para diagnóstico.
• Parar impersonação: retorna a sessão ao administrador original.
• Marcar e-mail verificado: toggle manual individual ou em lote.

Roles e permissões

• Atualizar roles: vincula um ou mais papéis (roles) ao usuário.
• Gerenciar roles: criar, editar, excluir e listar papéis da plataforma.
• Gerenciar permissões: criar, editar, excluir e listar permissões granulares.

Financeiro do usuário

• Adicionar saldo: credita a carteira (wallet) com descrição auditável.
• Debitar saldo: lança débito com motivo registrado.
• Histórico de saldo: consulta de movimentação completa.
• Transações: lista de transações financeiras do usuário.

Preferências

• Preferências gerais: idioma, fuso, tema.
• Privacidade: consentimentos e visibilidade de dados.
• Notificações: canais habilitados por tipo de evento.

Atividades

• Histórico de atividades: log de ações, logins, alterações sensíveis.
• Anotações internas: notas privadas do administrador sobre o usuário.

Como acessar

1. Entre em /admin.
2. Abra Settings → Usuários ou diretamente /admin/settings/users.
3. Selecione um usuário para ver o painel detalhado ou clique em Novo para criar.

Tutoriais

Criar um administrador de tenant

1. Acesse /admin/settings/users/create.
2. Informe nome, e-mail e senha inicial.
3. Selecione o tenant e a empresa (se aplicável).
4. Em Roles, marque tenant-admin.
5. Salve e comunique as credenciais por canal seguro.

Impersonar um usuário para suporte

1. Em /admin/settings/users, localize o usuário.
2. Clique em Impersonar (/admin/settings/users/{id}/impersonate).
3. Você é redirecionado para a área do usuário com uma tarja de "modo impersonação".
4. Ao concluir, clique em Parar impersonação (/admin/stop-impersonation).

Bloquear e revogar sessões de um usuário suspeito

1. Acesse o perfil do usuário.
2. Clique em Bloquear - logins futuros são rejeitados.
3. Clique em Revogar todas as sessões - as sessões ativas são invalidadas imediatamente.
4. Registre o motivo em Anotações.

Ajustar saldo manualmente

1. No perfil do usuário, aba Financeiro.
2. Adicionar saldo ou Debitar saldo informando valor e descrição.
3. A movimentação aparece em Histórico de saldo e em Transações.

Integrações

• Plano e assinaturas - usuários podem ter assinaturas ativas; veja planos-e-pacotes.md.
• Afiliados - usuários podem atuar como afiliados; veja afiliados-admin.md.
• Compliance / LGPD - exportação e anonimização de dados pessoais; veja compliance-lgpd.md.
• Eventos - user.created, user.updated, user.deleted, user.login, user.logout, user.password.changed são emitidos no Event Bus.

Perguntas frequentes

O usuário final precisa estar vinculado a uma empresa? Não. A plataforma suporta usuários sem empresa (company_id = NULL). Isso é obrigatório por design.

Posso mover um usuário de tenant? Não via UI. Mudança de tenant exige operação controlada pelo super-admin por impacto em dados históricos.

Impersonar dispara e-mail ou notifica o usuário? Não notifica automaticamente, mas fica auditável no log de atividades.

Quantas sessões simultâneas são permitidas? Depende da configuração de segurança da plataforma em Platform → Segurança.

Posso importar usuários em massa? Não há importação em massa pela UI de usuários. Use rotinas de seed ou integração via API interna.

Debitar saldo pode deixar o saldo negativo? Não. A regra de carteira impede saldo negativo, retornando erro.

Reset de senha expira? Sim, conforme política configurada em Platform → Segurança.

Excluir usuário apaga histórico financeiro? Não. Para conformidade LGPD, dados financeiros seguem retenção fiscal configurada.

Limitações, políticas e avisos

• Tenant-admin não pode promover outro usuário a super-admin.
• Impersonação não concede privilégios acima dos do administrador atuante.
• Revogar sessões desloga também dispositivos móveis registrados.
• Exclusão de usuário emite evento user.deleted consumido por plugins dependentes.
• Ações sensíveis (reset, impersonar, bloquear, ajuste de saldo) ficam em auditoria permanente.

Relacionados

• tenants-whitelabel-management.md
• companies-management.md
• compliance-lgpd.md
• notifications-admin.md