📊 API de Relatórios Aulapp

Documentação Completa da API de Performance Educacional

v2.0.0 • Firebase Realtime Database

🎯 Visão Geral

A API de Relatórios Aulapp é uma solução completa para análise de performance educacional que combina dados estruturados do MySQL com dados de atividades em tempo real do Firebase Realtime Database, oferecendo insights profundos sobre o desempenho dos estudantes.

🚀 Arquitetura Moderna

Node.js + TypeScript + Express para máxima performance e confiabilidade

MySQL + Firebase Realtime Database para dados híbridos estruturados e em tempo real

Prisma ORM para queries otimizadas e type-safety

📈

Métricas Avançadas

Estatísticas completas de performance, rankings automáticos e análises comparativas entre turmas, estudantes e recursos educacionais.

🏗️

Análise Hierárquica

Dados agregados em múltiplos níveis: Instituição → Curso → Disciplina → Lição para análise granular e drill-down completo.

👥

Classificação de Estudantes

Categorização automática inteligente: Avançado (≥75%), Intermediário (50-74%), Deficiente (<50%) com distribuição percentual.

⏱️

Análise Temporal

Comparações período-a-período, análise de tendências e indicadores de melhoria para acompanhamento longitudinal.

🎯

Filtros Avançados

Filtros por turma, tipo de recurso, período temporal, paginação inteligente e remoção de dados expirados.

📊

Integração Looker

APIs otimizadas para consumo direto pelo Looker, permitindo dashboards interativos e relatórios automatizados.

🔐 Autenticação e Segurança

🛡️ Configurações de Segurança

  • Rate Limiting: 100 requisições por IP a cada 15 minutos
  • CORS: Configurado para aceitar qualquer origem (desenvolvimento)
  • Helmet: Headers de segurança aplicados
  • Trust Proxy: Configurado para load balancers e proxies

Headers Recomendados

Content-Type: application/json Accept: application/json X-Requested-With: XMLHttpRequest

🔗 Endpoints Principais

Base URL: https://34.195.218.186.sslip.io/api/reports/performance

GET /institution/{institutionId} IMPLEMENTADO

Relatório Completo de Performance

Retorna dados completos de performance da instituição incluindo estatísticas agregadas, rankings de estudantes, performance por recursos e turmas, dados hierárquicos e classificações de alunos.

Funcionalidades Incluídas

  • 📊 Estatísticas gerais (média, total de tentativas, turmas acima/abaixo de 75%)
  • 🏆 Rankings de top/bottom performers
  • 📚 Performance por recursos (TE, AC, GA, SI, PS, MA, CO)
  • 🎓 Performance por turmas
  • 🏗️ Agregações hierárquicas (Curso → Disciplina → Lição)
  • 👥 Classificações de estudantes (Advanced/Intermediate/Deficient)
  • 📈 Análise temporal (quando filtros de data são aplicados)
GET /institution/{institutionId}/summary IMPLEMENTADO

Resumo Estatístico

Versão condensada do relatório com métricas principais e top 10 rankings. Ideal para dashboards e cards de resumo.

GET /institution/{institutionId}/classes IMPLEMENTADO

Performance por Turmas

Análise comparativa detalhada entre turmas com identificação de classes acima/abaixo de 75% de performance.

GET /institution/{institutionId}/resources IMPLEMENTADO

Performance por Recursos

Análise por tipo de atividade educacional (TE=Avaliação, AC=Atividade, GA=Gamificada, SI=Simulado, PS=Pacote Scorm, MA=Material de Apoio) com métricas de acerto por recurso.

GET /institution/{institutionId}/students/ranking IMPLEMENTADO

Ranking de Estudantes

Rankings de melhores e piores performers com identificação de alunos que necessitam atenção especial.

GET /health ● ATIVO

Health Check

Verifica status do servidor, conexões com banco de dados e integridade dos serviços.

⚡ Endpoints de Fluência (Planejados)

Futuros endpoints para análise de fluência em atividades de fala:

  • GET /fluency/spelling/{studentId} - Fluência em soletrar
  • GET /fluency/syllable/{studentId} - Fluência em silabar
  • GET /fluency/word-reading/{studentId} - Fluência em leitura de palavras
  • GET /fluency/text-reading/{studentId} - Fluência em leitura de textos

⚡ Funcionalidades Avançadas

🏗️ Análise Hierárquica Multinível

A API oferece agregações de dados em múltiplos níveis organizacionais, permitindo drill-down completo:

Níveis de Agregação

  • 📚 Course Performance: Dados consolidados por curso acadêmico (ex: Matemática, Português)
  • 📖 Discipline Performance: Performance detalhada por disciplinas dentro de cada curso (ex: Álgebra, Geometria)
  • 📝 Lesson Performance: Performance granular por lições específicas (ex: Equações do 1º grau)

Cada nível inclui: Total de estudantes, tentativas, acertos, média de performance e hierarquia completa.

👥 Sistema de Classificação Inteligente

Categorização Automática de Estudantes

Classificação Critério Descrição Ação Recomendada
🟢 Advanced ≥75% Excelente performance Atenção mínima, desafios adicionais
🟡 Intermediate 50-74% Performance moderada Acompanhamento regular
🔴 Deficient <50% Performance baixa Intervenção necessária

📈 Análise Temporal Avançada

Quando filtros dateFrom e dateTo são aplicados, a API calcula automaticamente:

🎯 Tipos de Recursos Educacionais

📝

TE - Avaliação

Avaliações formais e exercícios de verificação de conhecimento

💪

AC - Atividade

Atividades práticas e exercícios de fixação

🎮

GA - Gamificada

Jogos educacionais e atividades lúdicas

🔬

SI - Simulado

Simulados e testes preparatórios

📦

PS - Pacote Scorm

Conteúdos SCORM interativos e padronizados

📄

MA - Material de Apoio

Materiais complementares e documentos de suporte

📝 Parâmetros de Consulta Detalhados

Parâmetro Tipo Obrigatório Descrição Exemplo
classIds string[] ❌ IDs das turmas separados por vírgula 456,789,123
resourceTypes string[] ❌ Tipos de recursos: TE,EX,GA,SI,AC,PS TE,EX
dateFrom string ❌ Data inicial (formato ISO) 2025-01-01
dateTo string ❌ Data final (formato ISO) 2025-12-31
removeExpired boolean ❌ Remover turmas expiradas true (padrão)
page number ❌ Página para paginação 1 (padrão)
limit number ❌ Limite por página (máx: 1000) 100 (padrão)

🔍 Exemplos de URLs com Parâmetros

# Relatório básico GET /institution/123 # Com filtros específicos GET /institution/123?classIds=456,789&resourceTypes=TE,EX&limit=50 # Com período temporal GET /institution/123?dateFrom=2025-01-01&dateTo=2025-03-31 # Filtros combinados GET /institution/123?classIds=456&resourceTypes=TE&dateFrom=2025-01-01&dateTo=2025-12-31&page=2&limit=200

📊 Estruturas de Resposta Detalhadas

Resposta Padrão da API

JSON Response Structure
{ "success": true, "message": "Relatório de performance gerado com sucesso", "data": { "metadata": { "institutionId": "123", "institutionName": "Colégio Exemplo", "reportDate": "2025-10-09T14:30:00Z", "filters": { "classIds": ["456", "789"], "resourceTypes": ["TE", "EX"], "dateFrom": "2025-01-01", "dateTo": "2025-12-31", "removeExpired": true }, "pagination": { "page": 1, "limit": 100, "total": 1250, "totalPages": 13 } }, "statistics": { "totalStudents": 150, "totalAttempts": 1500, "overallAverage": 72.5, "classesAbove75": 8, "classesBelow75": 12, "averageVariation": -2.3 }, "coursePerformance": [ { "courseId": "1", "courseName": "Matemática", "totalStudents": 50, "totalAttempts": 300, "correctAnswers": 240, "averageScore": 80.0 } ], "disciplinePerformance": [ { "disciplineId": "2", "disciplineName": "Álgebra", "courseId": "1", "courseName": "Matemática", "totalStudents": 25, "totalAttempts": 150, "correctAnswers": 120, "averageScore": 80.0 } ], "lessonPerformance": [ { "lessonId": "3", "lessonName": "Equações do 1º grau", "disciplineId": "2", "disciplineName": "Álgebra", "courseId": "1", "courseName": "Matemática", "totalStudents": 25, "totalAttempts": 75, "correctAnswers": 60, "averageScore": 80.0 } ], "studentClassifications": [ { "classification": "advanced", "threshold": "≥75%", "count": 90, "percentage": 60.0, "students": ["student1", "student2"] }, { "classification": "intermediate", "threshold": "50-74%", "count": 45, "percentage": 30.0, "students": ["student3", "student4"] }, { "classification": "deficient", "threshold": "<50%", "count": 15, "percentage": 10.0, "students": ["student5"] } ], "resourcePerformance": [...], "classPerformance": [...], "topStudents": [...], "bottomStudents": [...], "detailedData": [...], "temporalVariation": { "currentPeriod": "2025-Q1", "previousPeriod": "2024-Q4", "variation": "+5.2%", "trend": "improving" } } }

Códigos de Status HTTP

Código Status Descrição Exemplo de Causa
200 OK Requisição bem-sucedida Dados retornados corretamente
400 Bad Request Parâmetros inválidos institutionId inválido
404 Not Found Recurso não encontrado Instituição não existe
429 Too Many Requests Rate limit excedido Mais de 100 req/15min
500 Internal Server Error Erro interno do servidor Falha na conexão com BD

💡 Exemplos Práticos de Uso

🎯 Casos de Uso Comuns

1. Dashboard Principal (Visão Executiva)

Objetivo: Criar cards principais para dashboard executivo

// Buscar resumo para exibir métricas principais const summary = await fetch('/institution/123/summary'); const data = await summary.json(); // Exibir nos cards: console.log({ mediaGeral: data.statistics.overallAverage, // 72.5% turmasAcima75: data.statistics.classesAbove75, // 8 turmas turmasAbaixo75: data.statistics.classesBelow75, // 12 turmas totalEstudantes: data.statistics.totalStudents, // 150 alunos totalTentativas: data.statistics.totalAttempts // 1500 tentativas });

2. Análise de Performance por Recursos

Objetivo: Gráfico de barras com performance por tipo de atividade

// Buscar dados por recursos const resources = await fetch('/institution/123/resources'); const data = await resources.json(); // Para gráfico de barras: const chartData = data.resourcePerformance.map(resource => ({ name: resource.resourceName, type: resource.resourceType, averageScore: resource.averageScore, totalAttempts: resource.totalAttempts, studentsCount: resource.studentsCount })); console.log('Dados do gráfico:', chartData);

3. Tabela de Ranking de Estudantes

Objetivo: Lista de estudantes para intervenção pedagógica

// Buscar ranking completo const ranking = await fetch('/institution/123/students/ranking'); const data = await ranking.json(); // Top 5 performers console.log('🏆 Melhores estudantes:', data.topStudents.slice(0, 5)); // Bottom 5 - necessitam atenção console.log('⚠️ Estudantes em risco:', data.bottomStudents.slice(0, 5)); // Classificações automáticas const classifications = data.studentClassifications; console.log(`Advanced: ${classifications.advanced.count} (${classifications.advanced.percentage}%)`); console.log(`Intermediate: ${classifications.intermediate.count} (${classifications.intermediate.percentage}%)`); console.log(`Deficient: ${classifications.deficient.count} (${classifications.deficient.percentage}%)`);

4. Análise Hierárquica Drill-Down

Objetivo: Navegação interativa Curso → Disciplina → Lição

// Buscar dados hierárquicos const report = await fetch('/institution/123'); const data = await report.json(); // Estrutura hierárquica para drill-down const hierarchy = { courses: data.coursePerformance, disciplines: data.disciplinePerformance, lessons: data.lessonPerformance }; // Exemplo: Filtrar disciplinas de um curso específico const mathDisciplines = hierarchy.disciplines.filter(d => d.courseId === "1"); console.log('Disciplinas de Matemática:', mathDisciplines); // Exemplo: Filtrar lições de uma disciplina específica const algebraLessons = hierarchy.lessons.filter(l => l.disciplineId === "2"); console.log('Lições de Álgebra:', algebraLessons);

📊 Exemplos de Filtros Avançados

Filtro por Período e Turmas Específicas

# Análise do 1º trimestre de 2025 para turmas específicas GET /institution/123?classIds=456,789&dateFrom=2025-01-01&dateTo=2025-03-31&limit=500 # Apenas exercícios e testes no último semestre GET /institution/123?resourceTypes=EX,TE&dateFrom=2025-07-01&dateTo=2025-12-31 # Dados completos sem turmas expiradas GET /institution/123?removeExpired=true&limit=1000

Paginação para Grandes Datasets

# Primeira página (primeiros 100 registros) GET /institution/123?page=1&limit=100 # Segunda página (registros 101-200) GET /institution/123?page=2&limit=100 # Página personalizada (registros 501-1000) GET /institution/123?page=3&limit=500

🔌 Integração com Ferramentas BI

Looker Studio / Google Data Studio

Configuração de Fonte de Dados:

  • Tipo: REST API / JSON
  • URL: https://seu-dominio.com/api/reports/performance/institution/123
  • Método: GET
  • Headers: Content-Type: application/json
  • Refresh: A cada 1 hora

Power BI

// Power Query M para Power BI let Source = Json.Document(Web.Contents("https://seu-dominio.com/api/reports/performance/institution/123")), data = Source[data], statistics = data[statistics], coursePerformance = data[coursePerformance], studentClassifications = data[studentClassifications] in data

Tableau

Configuração Web Data Connector:

  1. Conectar → Para um Servidor → Web Data Connector
  2. URL: https://seu-dominio.com/api/reports/performance/institution/123
  3. Configurar refresh automático
  4. Mapear campos JSON para tabelas Tableau

🧪 Testador Interativo da API

🚀

Teste os Endpoints em Tempo Real

Configure os parâmetros e teste os endpoints diretamente no seu navegador

URL inválida. Use formato: https://dominio.com
ID da instituição é obrigatório

🎛️ Filtros Avançados

Separados por vírgula • Padrão: todas as turmas
Padrão: desde o início
Padrão: até hoje
Ctrl/Cmd + clique para múltiplos • Padrão: todos
Padrão: 1
Padrão: 100 • Máximo: 1000
https://34.195.218.186.sslip.io/api/reports/performance/institution/1
🏥
Health Check
Verifica se o servidor está funcionando corretamente
GET /health
📊
Relatório Completo
Dados completos de performance da instituição
GET /api/reports/performance/institution/{id}
📋
Resumo Executivo
Estatísticas resumidas e principais indicadores
GET /api/reports/performance/institution/{id}/summary
🎓
Performance por Turmas
Análise de desempenho agrupada por turmas
GET /api/reports/performance/institution/{id}/classes
📚
Performance por Recursos
Análise de desempenho por recursos educacionais
GET /api/reports/performance/institution/{id}/resources
🏆
Ranking de Estudantes
Ranking dos melhores e piores estudantes
GET /api/reports/performance/institution/{id}/students/ranking
Selecione um endpoint acima para habilitar
Resposta da API 

                

            

        


        

            
🔌 Guia de Integração

            
            
🚀 Configuração Rápida

            

                
Requisitos Mínimos

                
    
                    
  • Node.js: ≥18.0.0
    • 
                    
  • MySQL: ≥8.0
    • 
                    
  • Firebase: Realtime Database configurado
    • 
                    
  • Rede: Acesso às URLs da API
    • 
                

            


            
1. Instalação Local

            

# Clone o repositório
git clone https://github.com/ies2/aulapp-reports-api.git
cd aulapp-reports-api

# Instale dependências
pnpm install

# Configure variáveis de ambiente
cp .env.example .env
# Edite .env com suas credenciais

# Gere cliente Prisma e execute migrações
pnpm db:generate
pnpm db:migrate

# Inicie o servidor
pnpm dev
            


            
2. Configuração de Ambiente

            

# .env
NODE_ENV=development
PORT=3001

# MySQL
DATABASE_URL="mysql://user:password@host:3306/database"

# Firebase
FIREBASE_PROJECT_ID=seu-projeto-firebase
FIREBASE_DATABASE_URL=https://seu-projeto-default-rtdb.firebaseio.com/
FIREBASE_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n"
FIREBASE_CLIENT_EMAIL=firebase-adminsdk@projeto.iam.gserviceaccount.com

# Segurança
ALLOWED_ORIGINS=*
            


            
📡 Integrações Testadas

            
            

                

                    
📊

                    
Looker Studio

                    
Connector REST API nativo com refresh automático e caching inteligente.

                

                

                    
⚡

                    
Power BI

                    
Power Query M personalizado para importação de dados JSON hierárquicos.

                

                

                    
🎨

                    
Tableau

                    
Web Data Connector para visualizações interativas e dashboards.

                

                

                    
📱

                    
Apps Mobile

                    
APIs RESTful compatíveis com React Native, Flutter e desenvolvimento nativo.

                

            


            
🛡️ Boas Práticas de Segurança

            

                
Recomendações de Produção

                
    
                    
  • Rate Limiting: Configurar limites apropriados por cliente
    • 
                    
  • CORS: Restringir origens em produção
    • 
                    
  • HTTPS: Sempre usar TLS em produção
    • 
                    
  • Monitoring: Implementar logs detalhados e alertas
    • 
                    
  • Cache: Configurar cache Redis para performance
    • 
                    
  • Load Balancer: Usar proxy reverso para escalabilidade
    • 
                

            


            
📈 Performance e Escalabilidade

            

                
                    

                        Métrica
                        Valor Típico
                        Limite Recomendado
                        Otimização
                    

                
                
                    

                        Tempo de Resposta
                        < 500ms
                        < 2s
                        Cache, paginação
                    

                    

                        Throughput
                        100 req/min
                        1000 req/min
                        Load balancer
                    

                    

                        Concurrent Users
                        50 usuários
                        500 usuários
                        Scaling horizontal
                    

                    

                        Payload Size
                        < 1MB
                        < 10MB
                        Compressão, filtros