Entidade: LostReason

Visão Geral

A entidade LostReason representa os motivos de perda de negociações no sistema CRM. É utilizada para categorizar e analisar por que determinadas oportunidades não foram convertidas em vendas, fornecendo insights valiosos para melhoria do processo comercial.

Estrutura da Entidade

Campos Principais

Campo	Tipo	Descrição	Obrigatório
`id`	number	Identificador único do motivo	✅ (auto)
`reason`	string	Descrição do motivo de perda	✅
`status`	enum	Status do motivo (active/inactive)	✅
`companyId`	number	ID da empresa proprietária	✅
`createdAt`	DateTime	Data/hora de criação	✅ (auto)
`updatedAt`	DateTime	Data/hora da última atualização	✅ (auto)

Relacionamentos

Company: Vinculado à empresa proprietária.

Deals: Relaciona-se com negociações perdidas.

Status Disponíveis

Status	Descrição
`active`	Motivo ativo e disponível para uso
`inactive`	Motivo desabilitado

Casos de Uso Detalhados

1. Análise de Perdas Comerciais

Cenário: Uma empresa deseja entender os principais motivos pelos quais perde negociações.

Fluxo:

Administrador cadastra motivos comuns (ex: "Preço alto", "Prazo inadequado").

Vendedores selecionam motivo ao marcar negociação como perdida.

Sistema gera relatórios de tendências de perda.

Gestão identifica pontos de melhoria no processo.

Benefícios: Insights para otimização do processo comercial e treinamento da equipe.

2. Padronização de Motivos

Cenário: Unificação da linguagem usada para classificar perdas.

Fluxo:

Empresa define lista padrão de motivos.

Todos os vendedores usam mesma classificação.

Relatórios ficam consistentes e comparáveis.

Análises históricas mantêm padrão.

Benefícios: Consistência nos dados e análises mais precisas.

3. Gestão de Motivos Ativos

Cenário: Controle sobre quais motivos estão disponíveis para uso.

Fluxo:

Administrador ativa/desativa motivos conforme necessidade.

Motivos obsoletos são desabilitados mas mantidos para histórico.

Novos motivos são adicionados conforme surgem.

Benefícios: Lista atualizada sem perder dados históricos.

Regras de Negócio

Criação de Motivos

Motivos são únicos por empresa.

Status padrão é "active" na criação.

Descrição deve ser clara e objetiva.

Controle de Acesso

Usuários só podem gerenciar motivos de sua empresa.

Isolamento por empresa (multi-tenancy).

Motivos inativos não aparecem em seleções ativas.

Ordenação e Exibição

Lista ordenada primeiro por status (ativos primeiro).

Depois ordenada por campo especificado (padrão: reason).

Motivos inativos aparecem no final da lista.

Histórico e Integridade

Motivos usados em negociações não podem ser excluídos.

Desativação preserva integridade referencial.

Relatórios históricos mantêm consistência.

Operações Disponíveis

Operação	Descrição	Método HTTP
Listar	Recupera motivos com filtros e ordenação	GET
Criar	Cria um novo motivo de perda	POST
Visualizar	Exibe detalhes de um motivo específico	GET
Atualizar	Modifica descrição ou status do motivo	PUT/PATCH
Excluir	Remove um motivo (se não usado)	DELETE

Fluxo de Uso

Exemplos de Motivos Comuns

Motivos Relacionados a Preço

"Preço muito alto"

"Orçamento insuficiente"

"Encontrou opção mais barata"

"Falta de verba aprovada"

Motivos Relacionados a Timing

"Prazo muito longo"

"Urgência não atendida"

"Sazonalidade inadequada"

"Projeto adiado"

Motivos Relacionados a Produto/Serviço

"Não atende necessidades"

"Funcionalidade insuficiente"

"Complexidade excessiva"

"Falta de integração"

Motivos Relacionados a Concorrência

"Escolheu concorrente"

"Parceiro preferencial"

"Relacionamento existente"

"Melhor proposta técnica"

Segurança e Boas Práticas

Para Desenvolvedores

Verificar uso em negociações antes de permitir exclusão.

Manter ordenação consistente (status primeiro, depois campo especificado).

Validar unicidade da descrição por empresa.

Para Usuários

Criar motivos específicos e claros.

Revisar periodicamente motivos obsoletos.

Desativar ao invés de excluir motivos em uso.

Usar linguagem padronizada e objetiva.

Para Gestores

Analisar relatórios de motivos frequentes.

Identificar padrões e oportunidades de melhoria.

Treinar equipe com base nos motivos mais comuns.

Limitações e Restrições

Motivos são específicos por empresa.

Não podem ser excluídos se usados em negociações.

Descrição deve ser única por empresa.

LostReason

Entidade: LostReason#

Visão Geral#

Estrutura da Entidade#

Campos Principais#

Relacionamentos#

Status Disponíveis#

Casos de Uso Detalhados#

1. Análise de Perdas Comerciais#

2. Padronização de Motivos#

3. Gestão de Motivos Ativos#

Regras de Negócio#

Criação de Motivos#

Controle de Acesso#

Ordenação e Exibição#

Histórico e Integridade#

Operações Disponíveis#

Fluxo de Uso#

Exemplos de Motivos Comuns#

Motivos Relacionados a Preço#

Motivos Relacionados a Timing#

Motivos Relacionados a Produto/Serviço#

Motivos Relacionados a Concorrência#

Segurança e Boas Práticas#

Para Desenvolvedores#

Para Usuários#

Para Gestores#

Limitações e Restrições#

Entidade: LostReason

Visão Geral

Estrutura da Entidade

Campos Principais

Relacionamentos

Status Disponíveis

Casos de Uso Detalhados

1. Análise de Perdas Comerciais

2. Padronização de Motivos

3. Gestão de Motivos Ativos

Regras de Negócio

Criação de Motivos

Controle de Acesso

Ordenação e Exibição

Histórico e Integridade

Operações Disponíveis

Fluxo de Uso

Exemplos de Motivos Comuns

Motivos Relacionados a Preço

Motivos Relacionados a Timing

Motivos Relacionados a Produto/Serviço

Motivos Relacionados a Concorrência

Segurança e Boas Práticas

Para Desenvolvedores

Para Usuários

Para Gestores

Limitações e Restrições