Visão Geral#
A entidade Pessoa representa pessoas no CUBO CRM. É uma entidade central que conecta negociações, organizações e atividades comerciais.Estrutura da Entidade#
Campos Principais#
| Campo | Tipo | Descrição | Obrigatório |
|---|
id | number | Identificador único da pessoa | ✅ (auto) |
name | string | Nome completo da pessoa | ✅ |
phone | string | Número de telefone | ❌ |
normalizedPhone | string | Telefone normalizado (só números) | ❌ (auto) |
companyId | number | ID da empresa proprietária | ✅ (auto) |
userId | number | ID do usuário criador | ✅ (auto) |
organizationId | number | ID da organização associada | ❌ |
status | enum | Status da pessoa (active, inactive) | ✅ |
createdAt | DateTime | Data/hora de criação | ✅ (auto) |
updatedAt | DateTime | Data/hora da última atualização | ✅ (auto) |
Relacionamentos#
Pessoa: Pertence a uma empresa
Usuário: Criada por um usuário específico
Organização: Pode estar associada a uma organização
Negociação: Possui muitas negociações
Campos personalizados: Campos personalizados
Anotação: Anotações e histórico de alterações
Normalização de Dados#
normalizedPhone é gerado automaticamente removendo caracteres não numéricos
Usado para otimizar buscas e comparações de telefone
Casos de Uso Detalhados#
1. Gestão de Contatos#
Cenário: Vendedor precisa organizar base de contatos.
Fluxo:Cadastrar pessoa com dados básicos
Associar a organização se existir
Adicionar campos personalizados específicos
Vincular a negociações ativas
Acompanhar histórico de interações
Fluxo:Capturar estado anterior da pessoa
Aplicar mudanças solicitadas
Registrar alterações via AnnotateChangesAction
Atualizar campos personalizados
Gerar anotação automática das mudanças
Regras de Negócio#
Criação e Validação#
Telefone é normalizado automaticamente
Status inicial sempre 'active'
Vinculação automática ao usuário e empresa autenticados
Controle de Acesso#
Isolamento total por empresa (multi-tenancy)
Todos os usuários da empresa podem ver todas as pessoas
Sem restrição por usuário criador após a criação
Normalização de Telefone#
Remove automaticamente caracteres especiais
Facilita buscas e integrações com WhatsApp
Mantém formato original e normalizado
Operações Disponíveis#
| Operação | Descrição | Método HTTP |
|---|
| Listar | Recupera pessoas com filtros e relacionamentos | GET |
| Criar | Cria nova pessoa com campos personalizados | POST |
| Visualizar | Exibe detalhes completos incluindo negociações | GET |
| Atualizar | Modifica dados com rastreamento de mudanças | PUT/PATCH |
| Excluir | Remove pessoa permanentemente | DELETE |
Fluxo de Importação#
Segurança e Boas Práticas#
Para Desenvolvedores#
Sempre normalizar telefones antes de salvar
Usar transações para operações de importação
Para Usuários#
Manter dados de contato atualizados
Usar campos personalizados para informações específicas do negócio
Associar pessoas a organizações quando aplicável
Limitações e Restrições#
Pessoas são específicas por empresa
Exclusão pode impactar negociações relacionadas
Campos personalizados seguem configuração da empresa
Modificado em 2025-06-16 14:54:41
