Visão Geral#
A entidade Funil representa os pipelines de vendas da empresa, organizando o fluxo de negociações através de diferentes etapas. Cada pipeline é vinculado a uma empresa e pode ter múltiplos usuários associados, com configurações específicas para distribuição de leads.Estrutura da Entidade#
Campos Principais#
| Campo | Tipo | Descrição | Obrigatório |
|---|
id | number | Identificador único do pipeline | ✅ (auto) |
name | string | Nome do pipeline | ✅ |
orderNr | number | Ordem de exibição do pipeline | ✅ |
timeEditAnnotation | number | Tempo limite para editar anotações (min) | ❌ |
status | enum | Status do pipeline (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#
Empresa: Vinculado à empresa proprietária.
Usuários: Relacionamento many-to-many com usuários (com pivot para distribuição).
Estágio: Possui múltiplas etapas ordenadas.
Negociação: Contém negociações distribuídas pelas etapas.
Filtros: Filtros personalizados por usuário.
Configurações de proposta: Configurações de proposta associadas.
Campos do Pivot Users#
| Campo | Tipo | Descrição |
|---|
splitter | number | Percentual de distribuição de leads |
count | number | Contador de leads recebidos |
Status Disponíveis#
| Status | Descrição |
|---|
active | Pipeline ativo e funcional |
inactive | Pipeline desabilitado |
Casos de Uso Detalhados#
1. Gestão de Funil de Vendas#
Cenário: Uma empresa deseja estruturar diferentes pipelines para diversos produtos ou equipes.O usuário cria pipelines específicos (ex: "Vendas B2B", "Vendas B2C").
Associa usuários com percentuais de distribuição.
Define etapas ordenadas para cada pipeline.
Configura filtros personalizados por usuário.
2. Distribuição Inteligente de Leads#
Cenário: Distribuição automática de leads entre vendedores baseada em percentuais.Administrador define percentual de distribuição para cada vendedor.
Sistema usa contador para balancear distribuição.
Leads são automaticamente atribuídos seguindo a proporção definida.
3. Controle de Anotações#
Cenário: Limite de tempo para edição de anotações em negociações.Pipeline define tempo limite para edição.
Usuários podem editar anotações dentro do prazo.
Após o prazo, anotações ficam bloqueadas para edição.
Regras de Negócio#
Criação de Pipelines#
Pipelines são únicos por empresa.
Ordem de exibição é ajustável.
Usuário criador é automaticamente associado se não especificado.
Controle de Acesso#
Usuários só podem acessar pipelines de sua empresa.
Usuários tipo "user" só veem pipelines onde estão associados.
Administradores veem todos os pipelines da empresa.
Distribuição de Leads#
Percentuais de distribuição devem somar 100%.
Contador mantém equilíbrio na distribuição.
Usuários inativos não recebem novos leads.
Reordenação de Etapas#
Etapas podem ser reordenadas via operação específica.
Ordem afeta visualização e fluxo de negociações.
Operações Disponíveis#
| Operação | Descrição | Método HTTP |
|---|
| Listar | Recupera pipelines com filtros e paginação | GET |
| Criar | Cria um novo pipeline | POST |
| Visualizar | Exibe detalhes de um pipeline específico | GET |
| Atualizar | Modifica pipeline e reordena etapas | PUT/PATCH |
| Atualizar Split | Modifica distribuição de usuários | PATCH |
| Reordenar Etapas | Altera ordem das etapas | PATCH |
| Excluir | Remove um pipeline | DELETE |
Fluxo de Uso#
Segurança e Boas Práticas#
Para Desenvolvedores#
Validar soma de percentuais de distribuição (100%).
Usar transações para operações de reordenação.
Verificar dependências antes de excluir pipeline.
Para Usuários#
Definir etapas lógicas e ordenadas.
Configurar distribuição balanceada entre vendedores.
Usar filtros para personalizar visualização.
Limitações e Restrições#
Pipelines são específicos por empresa.
Usuários só acessam pipelines onde estão associados.
Exclusão requer transferência de negociações ativas.
Percentuais de distribuição devem totalizar 100%.
Modificado em 2025-06-16 16:43:27
