Pular para o conteúdo principal

Introdução

🎯 O que este módulo faz?​

O módulo Users permite gerenciar usuários registrados. Na Plataforma OneEntry, existem as ferramentas necessárias para trabalhar com usuários registrados.

📖 Explicação Simples​

Toda aplicação precisa de gerenciamento de usuários:

  • 📝 Perfis de Usuário - Gerenciar informações do usuário
  • 💾 Dados de Usuário Personalizados - Armazenar dados específicos da aplicação (objeto de estado)
  • 🔍 Busca de Usuário - Pesquisar e filtrar usuários

✨ Conceitos Chave​

O que é um Usuário?​

Um Usuário é uma conta registrada em sua aplicação:

  • Informações Básicas - Nome, e-mail, telefone
  • Autenticação - Armazenamento seguro de senhas
  • Objeto de Estado - Dados personalizados da aplicação
  • Carimbos de Data/Hora - Data de registro, último login
  • Status - Ativo, inativo, bloqueado
  • Permissões - Funções e níveis de acesso do usuário

Estrutura do Usuário​

Cada usuário tem esta estrutura:

{
  id: 8,                                    // ID do Usuário
  identifier: 'test@test.ru',               // Identificador do usuário (e-mail/login)
  authProviderIdentifier: 'email',          // Tipo de provedor de autenticação
  formIdentifier: 'reg',                    // Identificador do formulário de registro
  formData: [                               // Dados do perfil do usuário
    { marker: 'name_reg', type: 'string', value: 'Ivan' },
    { marker: 'phone_reg', type: 'string', value: '+19258382556' },
  ],
  groups: [1],                              // Grupos de usuários para permissões
  state: {},                                // Dados personalizados da aplicação
  moduleFormConfigs: [],                    // Configurações adicionais do formulário
  total: "1"                                // Contagem total (para paginação)
}

Campos Chave:

  • id - Identificador único do usuário
  • identifier - Login do usuário (e-mail, telefone, nome de usuário)
  • authProviderIdentifier - Método de autenticação utilizado (e-mail, telefone, etc.)
  • formData - Array de campos do formulário com informações do perfil do usuário
  • groups - Array de IDs de grupos para controle de acesso
  • state - Objeto JSON personalizado para dados específicos da aplicação

Obter usuário com dados de estado personalizados​

Benefícios:

  • 🔒 Seguro - Hashing de senhas, autenticação segura
  • 📋 Validado - Validação de e-mail e dados
  • 🔄 Autenticado - Sessões baseadas em token
  • 💾 Persistente - Dados armazenados no banco de dados

Objeto de Estado do Usuário​

Você pode armazenar os dados necessários para o funcionamento da sua aplicação em um objeto de estado. Quando mudar o usuário, adicione os dados necessários ao estado. Quando os dados do usuário forem recebidos posteriormente, eles conterão um objeto de estado.

Um exemplo em que adicionamos informações ao usuário sobre quantos pedidos ele fez. Adicione um campo "orderCount" com o valor ao objeto de estado.

O objeto de estado é um armazenamento de dados personalizados por usuário:

Caso de UsoExemplo de EstadoDescrição
E-commerce{ orderCount: 5, totalSpent: 499.99 }Rastrear histórico de compras
Site de Conteúdo{ articlesRead: 25, bookmarks: [1,2,3] }Rastrear consumo de conteúdo
Aplicativo Social{ postsCount: 42, followers: 150 }Rastrear métricas sociais
Jogos{ level: 15, score: 9500, achievements: [...] }Rastrear progresso no jogo
SaaS{ plan: 'premium', usage: 75 }Rastrear dados de assinatura

Fluxo de Trabalho do Usuário​

1. O usuário preenche o formulário de registro
   (E-mail, senha, nome)
   ↓
2. createUser() chamado
   (OneEntry valida e faz hash da senha)
   ↓
3. Conta de usuário criada
   (Armazenada no banco de dados)
   ↓
4. O usuário faz login
   (authenticateUser() verifica credenciais)
   ↓
5. Token de autenticação retornado
   (Usado para solicitações subsequentes)
   ↓
6. A aplicação atualiza o estado do usuário
   (Dados personalizados como orderCount)
   ↓
7. Dados do usuário buscados conforme necessário
   (getUserById() com estado atual)

Por que usar o Módulo de Usuários?​

BenefícioDescrição
Autenticação SeguraHashing de senhas, gerenciamento de tokens
Gerenciamento de UsuáriosLer, atualizar, excluir usuários
Armazenamento de Dados PersonalizadosObjeto de estado para dados específicos da aplicação
Validação de E-mailVerificação automática do formato do e-mail
Prevenção de DuplicatasImpede registro de e-mail duplicado
Gerenciamento de SessõesAutenticação baseada em token

📋 O que você precisa saber​

Provedor de Autorização​

Os usuários no OneEntry são gerenciados através de um sistema de provedor de autorização que lida com mecanismos de registro e autenticação.

Pontos chave:

  • Os usuários se registram através de formulários configurados no painel de administração do OneEntry
  • Cada usuário está associado a um provedor de autenticação (e-mail, telefone, etc.)
  • Os dados do usuário são armazenados em campos de formulário definidos por formData
  • Metadados adicionais são armazenados no objeto state

O Objeto de Estado do Usuário é Flexível​

O objeto de estado pode armazenar qualquer dado JSON personalizado

Melhores práticas:

  • Armazene apenas dados específicos da aplicação
  • Mantenha o objeto de estado organizado com objetos aninhados
  • Atualize todo o objeto de estado (espalhe os dados existentes)
  • Não armazene dados sensíveis no estado

Segurança da Senha​

O OneEntry lida automaticamente com a segurança da senha

Sua responsabilidade:

  • Impor requisitos de senha (comprimento, complexidade)
  • Validar a senha no lado do cliente antes de enviar
  • Nunca registre senhas
  • Use HTTPS para todas as solicitações de autenticação

Gerenciamento de Tokens de Autenticação​

Armazene e use tokens de autenticação de forma segura

Melhores práticas para tokens:

  • Armazene em cookies HTTP-only sempre que possível
  • Use tempos de expiração curtos (1-2 horas)
  • Implemente tokens de atualização para sessões longas
  • Limpe o token ao sair
  • Nunca exponha tokens em URLs

Validação do Registro do Usuário​

Sempre valide a entrada do usuário antes do registro

Atualizando o Estado do Usuário com Segurança​

Sempre preserve o estado existente ao atualizar:

// ❌ Ruim - Sobrescreve todo o estado
const userstate = {
  orderCount: 1
}

// ✅ Bom - Preserve o estado existente
const userstate = {
  ...user.state, // Espalhe o estado existente
  orderCount: (user.state.orderCount || 0) + 1  // Atualize campo específico
}

Prevenção de E-mail Duplicado​

O OneEntry previne automaticamente o registro de e-mails duplicados

Melhor prática: Verifique o status de erro e mostre uma mensagem amigável ao usuário.

Paginação de Usuários​

Para grandes bases de usuários, sempre pagine ao buscar múltiplos usuários

💡 Notas Importantes​

Autorização Necessária​

A maioria dos métodos de usuário requer autorização através do módulo AuthProvider. Certifique-se de autenticar o usuário primeiro antes de chamar métodos de gerenciamento de usuários.

Dados do Formulário do Usuário​

Os dados do usuário são estruturados de acordo com os formulários configurados no painel de administração do OneEntry:

  • Cada usuário tem um formIdentifier que referencia o formulário de registro utilizado
  • Os dados do usuário são armazenados no array formData com marcadores, tipos e valores
  • Os tipos de campo suportados incluem: string, integer, float, date, dateTime, time, text, textWithHeader, image, groupOfImages, file, radioButton, list, entity, timeInterval

Diretrizes do Objeto de Estado​

Melhores práticas para o objeto de estado:

  • Armazene apenas dados específicos da aplicação
  • Mantenha o estado organizado com objetos aninhados
  • Atualize todo o estado (espalhe os dados existentes)
  • Não armazene dados sensíveis (senhas, tokens)
  • Não armazene grandes dados binários
  • Use convenções de nomenclatura consistentes

Notificações Push​

Use addFCMToken() e deleteFCMToken() para gerenciar tokens do Firebase Cloud Messaging para enviar notificações push aos usuários.

Dados de Notificação​

Ao atualizar usuários, você pode fornecer um objeto notificationData contendo:

  • email - Endereço de e-mail para notificações
  • phonePush - Array de números de telefone para notificações push
  • phoneSMS - Número de telefone para notificações SMS

📊 Tabela de Referência Rápida​

MétodoDescriçãoCaso de Uso
getUser()Obter dados do usuário autorizadoBuscar perfil do usuário atual
updateUser()Atualizar informações do usuárioAtualizações de perfil, mudanças de estado
archiveUser()Arquivar conta de usuárioExcluir suavemente a conta do usuário
deleteUser()Excluir usuário permanentementeExcluir permanentemente a conta do usuário
addFCMToken()Adicionar token FCM para notificações pushHabilitar notificações push
deleteFCMToken()Remover token FCMDesabilitar notificações push

❓ Perguntas Comuns (FAQ)​

O que é o objeto de estado do usuário e como devo usá-lo?​

O objeto de estado é um armazenamento JSON flexível para dados específicos do usuário na aplicação. Use-o para rastrear métricas personalizadas como contagem de pedidos, preferências ou progresso. Sempre espalhe o estado existente ao atualizar para evitar sobrescrever outros dados.

Como atualizo as informações do perfil do usuário?​

Use updateUser() para modificar os dados do perfil do usuário. Você pode atualizar campos de dados do formulário, configurações de notificação e o objeto de estado. Lembre-se de autenticar o usuário primeiro usando o módulo AuthProvider.

Qual é a diferença entre archiveUser() e deleteUser()?​

archiveUser() é uma exclusão suave que oculta o usuário, mas preserva os dados (pode ser restaurado). deleteUser() remove permanentemente o usuário e todos os dados associados (não pode ser desfeito). Use arquivamento, a menos que você precise de remoção completa dos dados.

Como lido com notificações push para usuários?​

Use addFCMToken() para registrar um token do Firebase Cloud Messaging para o usuário. Isso permite enviar notificações push para seus dispositivos. Use deleteFCMToken() quando eles fizerem logout ou desabilitarem notificações.

Posso armazenar dados sensíveis no objeto de estado do usuário?​

Não! Nunca armazene senhas, tokens, números de cartão de crédito ou outros dados sensíveis no objeto de estado. Ele não é criptografado especificamente para dados sensíveis. Use sistemas seguros e projetados para informações sensíveis.

Como busco dados do usuário após o registro?​

Após o registro e autenticação bem-sucedidos, use getUser() para buscar os dados do usuário autenticado, incluindo suas informações de perfil e objeto de estado personalizado.

🎓 Melhores Práticas​

  • Valide a entrada antes do registro - Verifique o formato do e-mail, a força da senha
  • Use HTTPS para autenticação - Criptografe todas as solicitações de login
  • Implemente requisitos de senha - Mínimo de 8 caracteres, letras maiúsculas e minúsculas, números
  • Armazene tokens de forma segura - Cookies HTTP-only ou armazenamento seguro
  • Preserve o estado existente - Espalhe os dados existentes ao atualizar o estado
  • Lide com e-mails duplicados - Capture erros 409 e mostre uma mensagem amigável ao usuário
  • Implemente logout - Limpe tokens e dados de sessão
  • Cache os dados do usuário - Reduza chamadas de API para usuários acessados com frequência

Mais informações sobre gerenciamento de usuários no painel de administração do OneEntry: https://doc.oneentry.cloudhttps://doc.oneentry.cloud/docs/category/users

Definição do módulo Users​


const { Users } = defineOneEntry(
  "sua-url-do-projeto", {
    "token": "seu-token-de-aplicativo"
  }
);

🔗 Documentação Relacionada​