Visão Geral#
A entidade Organização 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#
Empresa: Vinculada à empresa proprietária.
Usuário: Usuário responsável pela organização.
Campos Personalizados: Campos personalizados (many-to-many).
Anotação: Histórico de alterações e anotações.
Negociações: 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.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.
2. Auditoria Automática#
Cenário: Rastreamento completo de todas as alterações realizadas na organização.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.
3. Campos Personalizados Dinâmicos#
Cenário: Diferentes empresas precisam de campos específicos para suas organizações.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.
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.
Modificado em 2025-06-16 14:51:21
