Skip to main content

Módulo 13: Dashboard & Relatórios — API

Status: Rascunho Inicial Regras de negócio: ver regras-negocio/13_dashboard.md Domínio: ver dominio/meta.md

1. Contratos de API (RESTful)​

1.1 Endpoints do Dashboard (Métricas e Widgets)​

Todas as chamadas abaixo validam as credenciais de segurança e aplicam filtros de escopo baseados na árvore hierárquica do usuário autenticado.

GET /api/dashboard/funil
  Auth: Todos os usuários autenticados
  Query: ?periodo=YYYY-MM&time_id=uuid (opcional)
  Return: {
    leads_novos: integer,
    leads_qualificados: integer,
    propostas_enviadas: integer,
    contratos_ativos: integer,
    taxa_conversao_pct: decimal
  }
  Nota: Se o usuário logado for Consultor, ignora a query time_id e filtra apenas a carteira dele.

GET /api/dashboard/metas
  Auth: Todos os usuários autenticados
  Query: ?periodo=YYYY-MM
  Return: {
    meta_valor: decimal,
    realizado_valor: decimal,
    percentual_atingimento: decimal,
    tipo_metrica: "QUANTIDADE_CONTRATOS | RECEITA_ADESAO | RECEITA_MENSALIDADE"
  }

GET /api/dashboard/ranking
  Auth: Gestor | Admin
  Query: ?periodo=YYYY-MM&time_id=uuid (opcional)
  Return: [
    { rank: 1, consultor_id: uuid, nome: string, total_contratos: integer, volume_receita: decimal },
    { rank: 2, consultor_id: uuid, nome: string, total_contratos: integer, volume_receita: decimal }
  ]

1.2 Motor de Relatórios Assíncronos​

Para evitar problemas de timeout em consultas na base de dados de grande volume, os relatórios são gerados assincronamente através de filas.

POST /api/relatorios/gerar
  Auth: Gestor | Admin
  Body:
  {
    "tipo": "PRODUCAO_CASCATA | DESCARTE_LEADS | VENCIMENTOS_RENOVACOES",
    "filtros": {
      "data_inicio": "date",
      "data_fim": "date",
      "time_id": "uuid | null"
    },
    "formato": "CSV | XLSX"
  }
  Return: 202 Accepted
  {
    "job_id": "uuid",
    "status": "PROCESSANDO",
    "criado_em": "datetime"
  }

GET /api/relatorios/status/{job_id}
  Auth: Gestor | Admin
  Return:
  {
    "job_id": "uuid",
    "status": "PROCESSANDO | CONCLUIDO | FALHOU",
    "progresso_pct": integer,
    "download_url": "string | null",
    "erro_mensagem": "string | null"
  }

2. Segurança e Boas Práticas​

RegraImplementação
Caching no RedisAs requisições de dashboard (funil, metas) devem ser cacheadas no Redis com chaves dinâmicas mapeadas por Tenant e Usuário (ex: tenant:{id}:user:{id}:dash:funil:{periodo}). TTL padrão de 15 minutos.
Sanitização de ParâmetrosBloquear e higienizar qualquer parâmetro de query SQL para evitar injeções de SQL nas queries dinâmicas de consolidação.
Download Expirável de RelatóriosA URL fornecida em download_url deve apontar para o Cloud Storage interno e usar assinatura com tempo de expiração curto (máximo de 15 minutos).
Isolamento MultitenantTodas as queries de relatórios e dashboard devem aplicar obrigatoriamente a cláusula WHERE tenant_id = current_tenant_id logo na primeira junção de tabelas.
View de HierarquiaUtilizar Views Recursivas (Common Table Expressions - CTE) ou tabelas de mapeamento de caminhos hierárquicos pré-calculados para resolver a busca de equipes apadrinhadas rapidamente na geração do ranking e relatórios.