API: Relatorios e Exportacoes
Endpoints para exportacao CSV, dashboard consolidado do nucleo, relatorios globais do super admin e transparencia publica.
Exportacoes CSV
Permissao: COORDENADOR / ADMINISTRADOR. Todos os CSVs retornam com encoding UTF-8 BOM para compatibilidade com Excel.
| Metodo | Rota | Descricao |
|---|---|---|
| GET | /api/relatorios/exportar/membros | Lista completa de membros (nome, email, cargo, status, data cadastro) |
| GET | /api/relatorios/exportar/financeiro | Lancamentos financeiros com filtros de data |
| GET | /api/relatorios/exportar/pedidos | Pedidos da loja (produto, comprador, status, valor) |
| GET | /api/relatorios/exportar/presencas | Presencas em eventos (membro, evento, data check-in) |
| GET | /api/relatorios/exportar/ranking | Ranking de pontos (posicao, membro, pontos mensal, all-time) |
Query params opcionais: dataInicio, dataFim (formato ISO). Header de resposta: Content-Type: text/csv; charset=utf-8.
Dashboard do Nucleo
Permissao: COORDENADOR / ADMINISTRADOR.
| Metodo | Rota | Descricao |
|---|---|---|
| GET | /api/relatorios/dashboard | Dados agregados para o painel administrativo do nucleo |
Estrutura da resposta
| Secao | Campos |
|---|---|
membros | total, ativos, pendentes, porCargo (objeto com contagem por cargo), porCategoria (distribuicao por categoria), cadastrosMes (array ultimos 6 meses com grafico de barras) |
financeiro | evolucao (array com receitas e despesas dos ultimos 6 meses) |
economia | totalCCCirculacao (total de Capixacoins em circulacao), totalCCDistribuidas (total distribuidas), transacoesMes (transacoes do mes corrente), saldoMedio (saldo medio por membro) |
loja | pedidosMes (total do mes), topProdutos (5 mais vendidos) |
eventos | totalMes (eventos realizados no mes corrente), mediaPresenca (media de presencas por evento) |
engajamento | topMembros (10 membros mais ativos por pontos) |
Graficos no Frontend
- Barras: Cadastros por mes (ultimos 6 meses), distribuicao por cargo
- Linha: Evolucao financeira (receitas vs despesas)
- Pizza: Distribuicao por categoria de membro
- Cards numericos: Total de membros, pendentes, CC em circulacao, pedidos do mes
- DataTable: Top membros com paginacao e ordenacao
Relatorios Globais (Super Admin)
Permissao: SUPER_ADMIN. Painel com visao consolidada de todos os nucleos.
| Metodo | Rota | Descricao |
|---|---|---|
| GET | /api/relatorios/global | Dados agregados de todos os nucleos para o super admin |
7 Abas do Painel Global
| Aba | Descricao | Dados |
|---|---|---|
| Visao Geral | KPIs consolidados | Total de membros, nucleos ativos, receita total, CC em circulacao |
| Membros | Analise de membros por nucleo | Tabela com total/ativos/pendentes por nucleo, crescimento mensal |
| Financeiro | Receitas e despesas globais | Evolucao financeira consolidada, receita por nucleo, top nucleos |
| Economia | Capixacoins em todos os nucleos | CC em circulacao por nucleo, distribuicao total, saldo medio global |
| Engajamento | Atividade dos membros | Eventos realizados, tarefas concluidas, ranking global de membros |
| Loja | Vendas globais | Pedidos por nucleo, top produtos globais, receita da loja |
| Planos | Assinaturas e conversao | Distribuicao de planos, taxa de conversao free→pago, churn |
DataTable nos Relatorios
Todas as tabelas no painel de relatorios (tanto nucleo quanto global) utilizam o componente DataTable:
- Ordenacao por qualquer coluna (click no header)
- Paginacao client-side
- Busca/filtro por texto
- Exportar para CSV diretamente da tabela
Transparencia
Permissao: qualquer membro autenticado. Dados simplificados conforme toggles do administrador.
| Metodo | Rota | Descricao |
|---|---|---|
| GET | /api/relatorios/transparencia | Retorna dados filtrados pelos toggles de transparencia configurados pelo admin |
Se um grupo de transparencia estiver desativado (master toggle off), a secao correspondente retorna null. Ver Configuracoes para detalhes dos toggles.
Frontend
A pagina de relatorios no frontend possui duas abas:
- Dashboards — Graficos e cards com os dados do endpoint
/relatorios/dashboard. Inclui graficos de evolucao financeira (linha), distribuicao por cargo (barras), cadastros por mes (barras), economia de CC (cards), e top membros (DataTable). - Exportar CSV — Botoes para download de cada relatorio. O usuario seleciona o tipo e opcionalmente filtra por periodo.