Skip to main content

Módulo 13: Dashboard & Relatórios

Status: Documentado

Domínio: ver Domínio/Entidade: Meta Comercial e Domínio/Entidade: Usuário

ATA de Referência: (Ainda não aprovada)

1. Visão Geral da Regra​

O Dashboard e o módulo de Relatórios fornecem inteligência de dados em tempo real e consolidações históricas para o gerenciamento comercial do Tenant.

O acesso, a totalização e a exibição das métricas são condicionados estritamente à posição e ao nível do usuário na árvore de hierarquia de vendas (Módulo 03).

2. Regra de Ouro: Visibilidade Hierárquica​

Como estabelecido no Módulo 03, a restrição de segurança base: "Apenas vejo o que está no meu ramo abaixo" aplica-se de forma incondicional a todas as consultas analíticas, tabelas de listagem, rankings e geração de relatórios.

Nível HierárquicoRestrição de Escopo de Dados
Consultor (N4)Apenas dados da sua própria carteira comercial (Leads, Propostas, Planos Contratados e Faturas emitidas para seus clientes).
Líder de Equipe (N3)Dados de sua carteira + somatório consolidado das carteiras dos consultores sob sua liderança direta.
Padrinho (N2 / N1)Visão expandida englobando sua equipe + somatório cascata de todas as equipes apadrinhadas na subárvore hierárquica.
Admin / DiretorVisão macro de 360 graus, englobando todos os dados do Tenant sem restrição de ramificação.

3. Visões do Dashboard (Widgets Analíticos)​

Os painéis de indicadores são segmentados por foco operacional:

3.1 Painel Comercial (Consultor / Líder)​

  • Funil de Vendas: Gráfico de funil computando a conversão de Leads Novos → Leads Qualificados → Propostas Enviadas → Contratos Ativos.
  • Velocímetro de Metas: Cálculo percentual de atingimento com base na Meta_Comercial ativa para o período (mês).
  • Pipeline de Vendas: Valor financeiro acumulado em propostas nos status ENVIADA e ACEITA (indicação de vendas potenciais em andamento).
  • Ranking do Time (Gestores e Líderes): Comparativo de performance mostrando os consultores com maior número de planos ativados no período.

3.2 Painel Operacional (Backoffice)​

  • Fila de Vistorias: Volume de vistorias em andamento por status (PENDENTE, EM_ANALISE), monitorando o SLA (Tempo Médio de Atendimento).
  • Fila de Assinaturas: Volume de contratos pendentes em AGUARDANDO_ASSINATURA.
  • Fila de Ativação: Contratos assinados aguardando conciliação da taxa de adesão.

3.3 Painel Executivo (Admin / Gestor)​

  • MRR (Monthly Recurring Revenue): Receita recorrente mensal consolidada com base em todos os planos contratados com status ATIVO e INADIMPLENTE.
  • Churn Rate: Proporção percentual de planos cancelados no mês frente ao total da carteira ativa no início do período.
  • Inadimplência Real: Proporção de planos suspensos ou inadimplentes comparados à receita total faturada (obtida via integração ERP).

4. Políticas de Performance e Cache​

Para garantir baixa latência e evitar sobrecarga do banco transacional (PostgreSQL):

  1. Caching de Widgets: Os dados analíticos do Dashboard de uso frequente devem ser cacheados no Redis com tempo de vida de 15 minutos (ou tempo parametrizado por tenant).
  2. Materialized Views: Consultas pesadas de consolidação de vendas históricas e árvore de hierarquia devem consumir views materializadas com atualização automatizada em segundo plano a cada 1 hora.
  3. Exportação Assíncrona: Toda geração de relatórios volumosos (CSV/XLSX) deve ser executada em background via fila de processamento (jobs). O CRM fornece um identificador de job (job_id) para que o frontend consulte o status da compilação e obtenha a URL final de download seguro.

5. Regras Inegociáveis​

[!IMPORTANT] Filtro Hierárquico no Banco de Dados. Toda query SQL agregadora (ex: COUNT, SUM) deve aplicar obrigatoriamente a cláusula de filtro com base nos usuários sob a ramificação do operador atual, sob pena de quebra de segurança e privacidade.

[!WARNING] Desacoplamento de Cálculo Financeiro MMN. O relatório de Produção em Cascata lista as vendas por nível da árvore. O CRM não calcula valores de pagamentos, taxas ou comissões financeiras multinível de forma interna. Essa atribuição pertence a módulos específicos de repasses ou integrações externas.