API Reference: Relatorios Globais (Super Admin)

Endpoints de relatorios globais para o Super Admin. Agregam dados de todos os nucleos com variacoes percentuais, rankings e KPIs. Base URL: /api/super-admin/reports. Todos requerem cargo SUPER_ADMIN.

Endpoints

7 Tabs do Dashboard

O frontend organiza os relatorios em 7 abas:

1. Visao Geral

KPIs globais com variacao percentual vs periodo anterior.

• Total de membros ativos (variacao % vs mes anterior)
• Total de nucleos ativos
• Eventos realizados no periodo
• Tarefas concluidas no periodo
• Receita total (R$)
• Capixacoins em circulacao

2. Nucleos

Ranking e comparacao entre nucleos.

• Top nucleos: Os 5 nucleos com melhor engajamento (membros ativos, eventos, tarefas)
• Bottom nucleos: Os 5 nucleos com menor engajamento
• Membros por nucleo (grafico)
• Eventos por nucleo (grafico)
• Crescimento de membros por nucleo ao longo do tempo

3. Membros

Metricas de membros da plataforma inteira.

• Total de membros por status (ATIVO, PENDENTE, INATIVO, SUSPENSO)
• Novos membros por mes
• Taxa de aprovacao de cadastros
• Distribuicao por cargo
• Distribuicao por plano (Free, Apoiador, Militante, Onca)

4. Financeiro

Consolidacao financeira de todos os nucleos.

• Receita total vs despesas totais
• Receita por nucleo
• Receita por categoria (mensalidade, doacao, loja, etc)
• Inadimplencia (pagamentos atrasados)
• Evolucao mensal de receita

5. Eventos

Metricas de eventos da plataforma.

• Total de eventos por tipo (PRESENCIAL, ONLINE, HIBRIDO)
• Taxa de presenca media
• Eventos por nucleo
• Evolucao mensal de eventos
• Top eventos por presenca

6. Economia

Economia de Capixacoins agregada.

• Total de CC em circulacao
• CC emitidos por origem (TAREFA, EVENTO, PLANO, REFERRAL, MANUAL)
• CC gastos por destino (LOJA)
• Saldo medio por membro
• Top membros por saldo
• Evolucao mensal de emissao vs gasto

7. IA Insights

Assessor nacional com acesso a ferramentas globais. Usa a IA (OpenAI) para gerar insights automaticos sobre a plataforma.

• Analise de tendencias de crescimento
• Identificacao de nucleos em risco (baixo engajamento)
• Sugestoes de acoes para melhorar metricas
• Comparacao entre nucleos similares
• Previsoes baseadas em dados historicos

A IA tem acesso a tools globais que consultam dados agregados de todos os nucleos, diferente da IA de nucleo que so acessa dados do nucleo especifico.

Metricas e Variacoes

Todos os endpoints de relatorio retornam metricas com variacao percentual:

{
  "total_membros": 1250,
  "variacao_membros": 12.5,      // +12.5% vs periodo anterior
  "total_eventos": 45,
  "variacao_eventos": -3.2,      // -3.2% vs periodo anterior
  "receita_total": 15000.00,
  "variacao_receita": 8.7,
  "top_nucleos": [
    { "nome": "MBL-ES", "membros": 320, "engajamento": 85.2 },
    { "nome": "MBL-SP", "membros": 450, "engajamento": 78.9 }
  ],
  "bottom_nucleos": [
    { "nome": "MBL-AC", "membros": 15, "engajamento": 22.1 }
  ]
}

Query Parameters