Pular para conteúdo

Metas (Comercial)

O que é

Telas em /vendas/metas-v2/** (menu Comercial → "Metas") onde o time Comercial define e acompanha metas de vendas e outras métricas do funil. Cada meta é um par (tipo de métrica, período) com um valor_meta; a tela cruza isso com o "realizado" calculado a partir da carteira/operações e mostra progresso, projeção e se a meta foi (ou vai ser) atingida.

Como funciona

  • Rotas:
  • /vendas/metas-v2 — tela principal ("Minhas Metas"), com visão Mensal (tabela de metas do mês) e Anual (matriz métrica × mês, com intervalo de meses selecionável).
  • /vendas/metas-v2/gerenciar — CRUD de metas (criar/editar valor-meta por tipo/período); acesso controlado pela permissão vendas_metas (ação create, via PermissionButton).
  • /vendas/metas-v2/tipos-metrica — cadastro dos tipos de métrica (nome, unidade, direção).
  • /vendas/metas-v2/:id/progresso — drill-down de uma meta específica (gráficos: linha/barra/composto com Recharts).
  • Menu também expõe /relatorios/comissoes ("Performance") ao lado de Metas — ver comissoes, documentada em rodada posterior.
  • Tipo de métrica tem uma direcao:
  • CRESCENTE (ex.: vendas) — quanto mais realizado, melhor; progresso = realizado / meta.
  • DECRESCENTE (ex.: inadimplência) — quanto menos, melhor.
  • ESTAVEL (métrica de margem/desvio) — o "percentual_atingido" é lido como desvio, e o progresso exibido é invertido (100 − percentual_atingido × 5, capado em 0).
  • Tipos podem ser manual (sem cálculo automático de realizado — aparecem como "Não aplicável" na coluna de projeção).
  • Grupos especiais de métrica de vendas (tratamento específico na tela mensal, não no banco):
  • VALOR_TOTAL_VENDAS (métrica legada) — linha expansível que, ao abrir, quebra o realizado em duas sub-linhas: "Empréstimo Novo" e "Demais" (via breakdown_vendas do progresso).
  • VALOR_VENDAS_EMPRESTIMO_NOVO + VALOR_VENDAS_DEMAIS (métricas novas) — a tela soma as duas numa linha-pai "Vendas" expansível, cada uma navegável individualmente.
  • Progresso de uma meta (MetaProgresso) traz: valor_realizado, qtde_operacoes, percentual_atingido, meta_atingida (bool) e projecao_atingira_meta (bool, projeção de trajetória antes do fim do período). A contagem de operações usada no cálculo varia por tipo: vendas/ticket/taxa/prazo → novas operações pagas no mês; inadimplência → contratos da carteira ativa com parcela vencendo no mês (inclui safras anteriores); manuais → não aplicável.
  • Visão anual: agrega as metas mensais por tipo de métrica numa matriz (linha = métrica, coluna = mês do intervalo selecionado), com célula colorida por status (verde = atingida, amarelo ≥ 90%, vermelho abaixo) e clique navega pro drill-down /progresso do mês.

Regras de negócio

⚠️ A documentar. Esta tela ainda não tem as regras de negócio levantadas do código.

O que entra aqui: invariante (o que nunca pode acontecer), permissão (quem pode fazer o quê), bloqueio (o que impede a ação e a mensagem que o usuário vê), cálculo (fórmula e arredondamento) e efeito colateral (o que mais muda quando isso acontece).

Regra só entra aqui com origem no código — arquivo e linha. Regra que alguém "acha que é assim" é pior que seção vazia, porque vira decisão de produto baseada em memória.

Onde vive no código

  • CRM (pages): apps/crm-menos-juros/client/src/pages/vendas/metas-v2/ (index.tsx, gerenciar.tsx, tipos-metrica.tsx, progresso.tsx, nova.tsx, form.tsx, [id].tsx)
  • CRM (serviço): apps/crm-menos-juros/client/src/services/metas-v2-service.ts (MetasV2Service — listarTiposMetrica, listarMetas, consultarProgresso, formatação de valores/percentuais/meses, NOMES_VENDAS_NOVAS)
  • DB: tabelas de metas e tipos de métrica (meta_vendas e afins) — não detalhadas nesta ingestão; ver schema em apps/crm-menos-juros/shared/schema.ts e migrations correspondentes.

Relacionado

comercial · comissoes · comissao

Histórico

  • 2026-07-10 (conversa): página criada como parte da ingestão de telas do Comercial fora do Kanban. Gap: profundidade de consultarProgresso (regra exata do "realizado" por tipo, no backend) não foi explorada — ver log.md.
  • 2026-07-10 (INGEST wiki, cluster Relatórios/Analytics): /relatorios/comissoes documentada em comissoes; cross-link adicionado.