---
name: Módulo Analytics
description: Dashboard analítico em /direcao/analytics com KPIs, gráficos Chart.js e comparativo mensal vs ano anterior.
type: project
originSessionId: 86576285-fa7a-44f0-8ed3-9a88bcd27a8e
---
## Analytics — implementado 2026-05-05

### Acesso
- URL: `/direcao/analytics` (item no menu, abaixo de Financeiro, ícone fa-chart-line)
- Controller: `App\Controllers\AnalyticsController`
- Apenas usuários `direcao` (com permissão se RBAC ativo: módulo `analytics`)

### Endpoints REST (`/direcao/analytics/api/*`)
- `/resumo?ano=2026` — 8 KPIs com delta% vs ano anterior (matrículas, cancelamentos, receita, despesa, lucro, aulas concluídas, alunos ativos, professores ativos)
- `/serie-mensal?ano=2026&metrica=receita|despesa|lucro|matriculas|cancelamentos|aulas` — 12 valores ano selecionado + 12 do anterior (para gráfico de linha comparativo)
- `/top-professores?ano=2026` — top 10 por aulas concluídas
- `/por-curso` — distribuição de matrículas ATIVAS por curso (pizza)
- `/por-status` — distribuição por status de matrícula (pizza)
- `/receita-por-categoria?ano=2026` — pizza top 8 categorias
- `/comparativo-meses?ano=2026` — tabela com 12 linhas (mês × 6 indicadores)

### Frontend
- Chart.js 4.4 via CDN
- Filtro de ano único (auto-popula com anos disponíveis no banco)
- Métrica do gráfico principal persistida em `localStorage.analytics_metrica`
- Cards KPI com border-l-4 colorido + delta% (↑↓→) com cor semafórica

### Cálculos importantes
- **Receita** = SUM(valor) lançamentos `tipo=credito AND status=pago` por `YEAR(data_pagamento)`
- **Despesa** = idem com `tipo=debito`
- **Lucro** = receita - despesa
- **Aulas concluídas** = COUNT aulas `status=concluida` por `YEAR(data_aula)`
- **Cancelamentos** = COUNT matriculas `status=cancelada` por `YEAR(data_cancelamento)`

**Why:** dashboard tinha só números crus. Analytics dá visão estratégica/temporal.

**How to apply:** se quiser adicionar nova métrica, adicionar case em `seriePorMes()` + opção na aba `met-tab` no frontend.