Visão Geral#
A entidade Stage representa as etapas de um pipeline, usadas para organizar o progresso das negociações. Cada etapa é vinculada a um pipeline e empresa, com suporte a campos personalizados.Estrutura da Entidade#
Campos Principais#
| Campo | Tipo | Descrição | Obrigatório |
|---|
id | number | Identificador único da etapa | ✅ (auto) |
name | string | Nome descritivo da etapa | ✅ |
pipeId | number | ID do pipeline associado | ✅ |
orderNr | number | Ordem da etapa no pipeline | ✅ (auto) |
lightBackground | string | Cor de fundo para tema claro | ❌ |
darkBackground | string | Cor de fundo para tema escuro | ❌ |
companyId | number | ID da empresa proprietária (via pipeline) | ✅ (auto) |
createdAt | DateTime | Data/hora de criação | ✅ (auto) |
updatedAt | DateTime | Data/hora da última atualização | ✅ (auto) |
Relacionamentos#
Funil: Vinculada a um Funil específico.
Empresa: Vinculada à empresa do usuário (via pipeline).
Negociação: Relaciona-se com negociações na etapa.
Campo Personalizado: Suporta campos personalizados.
Status Disponíveis#
| Status | Descrição |
|---|
active | Etapa ativa e funcional |
deactivated | Etapa desabilitada |
Casos de Uso Detalhados#
1. Gestão de Pipelines#
Cenário: Uma empresa deseja estruturar seu funil de vendas com etapas específicas.O usuário cria etapas como "Prospecção", "Proposta", "Fechamento".
Associa campos personalizados a cada etapa.
Move negociações entre etapas, acompanhando métricas como total de negociações e preço.
Regras de Negócio#
Criação de Etapas#
Etapas são únicas por pipeline.
Ordem definida automaticamente, mas ajustável.
Vinculação automática à empresa do pipeline.
Controle de Acesso#
Usuários só podem gerenciar etapas de pipelines de sua empresa.
Isolamento por empresa (multi-tenancy).
Etapas desativadas não recebem novas negociações.
Segurança#
Exclusão de etapas exige movimentação de negociações associadas.
Validação de campos personalizados obrigatórios ao mover negociações.
Operações Disponíveis#
| Operação | Descrição | Método HTTP |
|---|
| Listar | Recupera etapas com paginação | GET |
| Criar | Cria uma nova etapa | POST |
| Visualizar | Exibe detalhes de uma etapa específica | GET |
| Atualizar | Modifica a etapa ou campos personalizados | PUT/PATCH |
| Excluir | Remove uma etapa | DELETE |
| Mudança em Massa | Move negociações entre etapas | POST |
Fluxo de Uso#
Segurança e Boas Práticas#
Para Desenvolvedores#
Garantir validação de campos obrigatórios ao mover negociações.
Usar transações para mudanças em massa.
Para Usuários#
Definir ordens lógicas para etapas.
Usar cores de fundo para facilitar identificação visual.
Verificar negociações antes de excluir etapas.
Limitações e Restrições#
Etapas são específicas por pipeline e empresa.
Não é permitido excluir etapas com negociações ativas sem transferência.
Modificado em 2025-06-16 17:04:57
