Entidade: People

Visão Geral

A entidade People 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

Company: Pertence a uma empresa

User: Criada por um usuário específico

Organization: Pode estar associada a uma organização

Deals: Possui muitas negociações

Customfields: Campos personalizados

Annotations: 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

Benefícios: Centralização de informações de contato e histórico comercial.

2. Atualização com Rastreamento

Cenário: Dados de contato precisam ser atualizados.
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

Benefícios: Histórico completo de alterações para auditoria.

Regras de Negócio

Criação e Validação

Nome é obrigatório

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

People

Entidade: People#

Visão Geral#

Estrutura da Entidade#

Campos Principais#

Relacionamentos#

Normalização de Dados#

Casos de Uso Detalhados#

1. Gestão de Contatos#

2. Atualização com Rastreamento#

Regras de Negócio#

Criação e Validação#

Controle de Acesso#

Normalização de Telefone#

Operações Disponíveis#

Fluxo de Importação#

Segurança e Boas Práticas#

Para Desenvolvedores#

Para Usuários#

Limitações e Restrições#