Entidade: Organization

Visão Geral

A entidade Organization representa as organizações clientes no sistema CRM. Cada organização é vinculada a uma empresa e usuário específico, com suporte a campos personalizados e sistema completo de auditoria através de anotações automáticas.

Estrutura da Entidade

Campos Principais

Campo	Tipo	Descrição	Obrigatório
`id`	number	Identificador único da organização	✅ (auto)
`name`	string	Nome da organização	✅
`companyId`	number	ID da empresa proprietária	✅
`userId`	number	ID do usuário responsável	✅
`createdAt`	DateTime	Data/hora de criação	✅ (auto)
`updatedAt`	DateTime	Data/hora da última atualização	✅ (auto)

Relacionamentos

Company: Vinculada à empresa proprietária.

User: Usuário responsável pela organização.

Customfields: Campos personalizados (many-to-many).

Annotations: Histórico de alterações e anotações.

Deals: Negociações associadas à organização.

Status Disponíveis

Status	Descrição
`active`	Organização ativa
`inactive`	Organização desabilitada

Traduções para Auditoria

Campo	Tradução
`name`	Nome
`status`	Status

Casos de Uso Detalhados

1. Gestão de Clientes

Cenário: Uma empresa deseja gerenciar informações completas de seus clientes organizacionais.

Fluxo:

O usuário cria uma organização com dados básicos.

Adiciona campos personalizados específicos do negócio.

Sistema gera anotações automáticas para todas as alterações.

Vincula negociações e propostas à organização.

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

2. Auditoria Automática

Cenário: Rastreamento completo de todas as alterações realizadas na organização.

Fluxo:

Usuário modifica dados da organização.

Sistema compara valores antigos com novos.

Gera anotações automáticas mostrando "Valor Antigo → Valor Novo".

Campos personalizados também são auditados automaticamente.

Benefícios: Transparência total e compliance com auditoria.

3. Campos Personalizados Dinâmicos

Cenário: Diferentes empresas precisam de campos específicos para suas organizações.

Fluxo:

Administrador configura campos personalizados.

Usuários preenchem campos específicos por organização.

Sistema audita alterações em campos personalizados.

Campos podem ser obrigatórios ou opcionais.

Benefícios: Flexibilidade para diferentes modelos de negócio.

Regras de Negócio

Criação de Organizações

Organizações são vinculadas automaticamente ao usuário criador.

Status padrão é "active".

Campos personalizados são opcionais na criação.

Controle de Acesso

Usuários só podem gerenciar organizações de sua empresa.

Usuários tipo "user" só veem organizações próprias.

Administradores veem todas as organizações da empresa.

Sistema de Auditoria

Todas as alterações geram anotações automáticas.

Formato padrão: "Campo: Valor Antigo → Valor Novo".

Campos sem valor anterior mostram "Sem informação".

Auditoria inclui campos personalizados.

Campos Personalizados

Cada organização pode ter valores únicos para campos personalizados.

Alterações em campos personalizados são auditadas.

Sistema cria ou atualiza registros conforme necessário.

Operações Disponíveis

Operação	Descrição	Método HTTP
Listar	Recupera organizações com filtros	GET
Criar	Cria uma nova organização	POST
Visualizar	Exibe detalhes completos da organização	GET
Atualizar	Modifica organização com auditoria completa	PUT/PATCH
Excluir	Remove uma organização	DELETE

Fluxo de Uso

Sistema de Auditoria Detalhado

Campos Básicos

Sistema compara $attributes atual com $dirty após alteração.

Usa traduções definidas para nomes amigáveis.

Formato: {Campo Traduzido}: {Valor Antigo} → {Valor Novo}.

Campos Personalizados

Busca registro existente por organizationId e customfieldId.

Se existe: compara valores e gera anotação se diferente.

Se não existe: cria novo registro e anota como "Sem informação → Novo Valor".

Segurança e Boas Práticas

Para Desenvolvedores

Sempre carregar relacionamentos necessários para evitar N+1.

Usar transações para operações que modificam múltiplas tabelas.

Validar campos obrigatórios antes de salvar.

Para Usuários

Manter informações atualizadas para melhor gestão.

Usar campos personalizados para dados específicos do negócio.

Revisar histórico de anotações para acompanhar mudanças.

Limitações e Restrições

Organizações são específicas por empresa.

Usuários tipo "user" só acessam organizações próprias.

Sistema de auditoria não pode ser desabilitado.

Campos personalizados dependem de configuração prévia.

Organization

Entidade: Organization#

Visão Geral#

Estrutura da Entidade#

Campos Principais#

Relacionamentos#

Status Disponíveis#

Traduções para Auditoria#

Casos de Uso Detalhados#

1. Gestão de Clientes#

2. Auditoria Automática#

3. Campos Personalizados Dinâmicos#

Regras de Negócio#

Criação de Organizações#

Controle de Acesso#

Sistema de Auditoria#

Campos Personalizados#

Operações Disponíveis#

Fluxo de Uso#

Sistema de Auditoria Detalhado#

Campos Básicos#

Campos Personalizados#

Segurança e Boas Práticas#

Para Desenvolvedores#

Para Usuários#

Limitações e Restrições#

Entidade: Organization

Visão Geral

Estrutura da Entidade

Campos Principais

Relacionamentos

Status Disponíveis

Traduções para Auditoria

Casos de Uso Detalhados

1. Gestão de Clientes

2. Auditoria Automática

3. Campos Personalizados Dinâmicos

Regras de Negócio

Criação de Organizações

Controle de Acesso

Sistema de Auditoria

Campos Personalizados

Operações Disponíveis

Fluxo de Uso

Sistema de Auditoria Detalhado

Campos Básicos

Campos Personalizados

Segurança e Boas Práticas

Para Desenvolvedores

Para Usuários

Limitações e Restrições