Skip to content
BranchesTags

Repository files navigation

PlusEduc API

Backend da plataforma PlusEduc, um sistema de gestão educacional inclusiva com foco em acompanhamento pedagógico, desempenho escolar e geração de atividades adaptadas com IA.

A aplicação foi construída com Spring Boot 3.4.1, Java 21, MongoDB, JWT Authentication, Swagger/OpenAPI e exportação de atividades em PDF.

Repositório de demonstração / portfólio. Credenciais e deploy real ficam fora do Git (.env, painel do provedor). Veja docs/desenvolvimento.md para rodar localmente.

Visão Geral

O PlusEduc API oferece recursos para:

  • autenticação de usuários com JWT
  • cadastro e gestão de alunos
  • gestão de professores
  • gestão de turmas
  • lançamento e consulta de notas
  • cálculo de desempenho e frequência
  • geração de atividades com IA
  • exportação de atividades em PDF
  • documentação interativa via Swagger

O projeto foi pensado para uso acadêmico e demonstração de um fluxo completo de backend para uma plataforma educacional.

Stack Tecnológica

  • Java 21
  • Spring Boot 3.4.1
  • Spring Web
  • Spring Security
  • Spring Data MongoDB
  • Spring Validation
  • Spring Actuator
  • JWT (jjwt)
  • Springdoc OpenAPI / Swagger UI
  • OpenPDF
  • Lombok
  • Maven

Arquitetura do Projeto

A estrutura principal do projeto segue o padrão:

src/main/java/PE/PlusEduc/
├── config/        # Segurança, Swagger, Mongo, CORS
├── controller/    # Endpoints REST
├── dto/           # Requests e Responses
├── exception/     # Exceções customizadas
├── handler/       # Tratamento global de erros
├── mapper/        # Conversão Entity ↔ DTO
├── model/         # Documentos MongoDB
├── repository/    # Repositórios Mongo
├── security/      # JWT e autenticação
├── service/       # Regras de negócio
│   └── ai/        # Geração de atividades com IA/mock
└── Application.java

Fluxo principal:

Controller -> Service -> Repository -> MongoDB

Principais Módulos

1. Autenticação

Responsável por login e cadastro de professores.

  • login com email e senha
  • geração de access token e refresh token
  • proteção de endpoints com JWT

2. Alunos

Gerencia alunos, lacunas de aprendizagem e vínculo com turma.

  • CRUD de alunos
  • consulta por turma
  • consulta por learning gap
  • média do aluno
  • frequência do aluno

3. Professores

Gerencia professores e especialidades.

  • CRUD de professores
  • busca por email
  • filtro por disciplina

4. Turmas

Gerencia turmas e matrícula de alunos.

  • CRUD de turmas
  • associação com professor
  • matrícula e remoção de aluno
  • média da turma
  • frequência média da turma

5. Notas

Registra e consulta notas.

  • CRUD de notas
  • média por aluno
  • média por disciplina
  • taxa de presença
  • faltas
  • consultas por período

6. Atividades

Gerencia atividades pedagógicas.

  • CRUD de atividades
  • atividades por turma
  • atividades por aluno
  • filtros por matéria e dificuldade
  • contagem por turma/criador

7. Geração com IA

Gera atividades adaptadas com base em matéria, tópico, dificuldade e lacunas do aluno.

Observação:

  • quando a API do Gemini não está disponível, o backend entra em modo demo e gera questões mockadas automaticamente

8. Exportação em PDF

Permite exportar atividades em PDF com layout educacional.

  • cabeçalho do PlusEduc
  • contexto pedagógico do aluno
  • questões formatadas
  • gabarito opcional
  • suporte a exportação com ou sem respostas

Segurança

A aplicação usa JWT Bearer Token.

Endpoints públicos

  • POST /api/auth/login
  • POST /api/auth/register/teacher
  • rotas do Swagger/OpenAPI

Endpoints protegidos

Todos os demais endpoints exigem:

Authorization: Bearer <token>

Documentação Swagger

A API possui documentação interativa com Springdoc.

URLs

No Swagger:

  1. faça login pelo endpoint /api/auth/login
  2. copie o accessToken
  3. clique em Authorize
  4. informe o token no formato Bearer

Exemplo:

Bearer seu_token_aqui

Configuração de Ambiente

Copie .env.example para .env e preencha com valores do seu ambiente local. O .env não é versionado.

cp .env.example .env

Use placeholders no exemplo; gere um JWT_SECRET forte antes de qualquer deploy. GEMINI_API_KEY é opcional — sem ela, a API usa o modo demo de geração de questões.

Configurações da Aplicação

A aplicação utiliza src/main/resources/application.properties (somente placeholders e variáveis de ambiente). Referência resumida: application-example.properties.

Como Executar Localmente

Pré-requisitos

  • Java 21
  • Maven 3.9+
  • MongoDB rodando localmente

1. Clonar o projeto

git clone https://github.com/PedroBeltraoDev/PlusEduc-BE.git
cd PlusEduc-BE

2. Configurar variáveis

Crie o .env ou configure as variáveis de ambiente necessárias.

3. Rodar a aplicação

Linux / macOS

./mvnw spring-boot:run

Windows

mvnw.cmd spring-boot:run

A aplicação subirá em:

http://localhost:8080

Build e Testes

Rodar testes

Linux / macOS

./mvnw test

Windows

mvnw.cmd test

Gerar pacote

Linux / macOS

./mvnw clean package

Windows

mvnw.cmd clean package

Docker Compose

O projeto possui um docker-compose.yml básico para subir a API empacotada como imagem.

Exemplo

version: '3.8'
services:
  pluseduc-api:
    image: pluseduc-api:latest
    ports:
      - "8080:8080"
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/actuator/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s

Observação:

  • esse compose pressupõe que a imagem pluseduc-api:latest já exista

Modelo de Dados

Student

Representa o aluno.

Campos principais:

  • id
  • name
  • email
  • birthDate
  • classId
  • learningGaps
  • active
  • createdAt
  • updatedAt

Teacher

Representa o professor.

Campos principais:

  • id
  • name
  • email
  • subjects
  • classroomIds
  • active

Classroom

Representa a turma.

Campos principais:

  • id
  • name
  • year
  • gradeLevel
  • teacherId
  • studentIds
  • subjects
  • active

Grade

Representa nota/presença.

Campos principais:

  • id
  • studentId
  • classroomId
  • subject
  • gradeValue
  • attendance
  • date
  • activityType
  • observations

Activity

Representa atividade pedagógica.

Campos principais:

  • id
  • title
  • subject
  • topic
  • difficultyLevel
  • questionsCount
  • format
  • classroomId
  • studentId
  • content
  • generatedByAi
  • aiProvider
  • createdBy
  • createdAt

User

Representa usuário autenticável.

Campos principais:

  • id
  • email
  • password
  • role
  • active
  • createdAt

Learning Gaps

Um dos diferenciais do projeto é o uso de lacunas de aprendizagem (learningGaps).

Cada aluno pode ter dificuldades registradas por:

  • matéria
  • tópico
  • nível de severidade
  • descrição
  • data de identificação
  • status de melhoria Esses dados podem ser usados para:
  • análise pedagógica
  • filtros de alunos
  • personalização de atividades
  • reforço adaptado com IA

Geração de Atividades com IA

O módulo de IA gera questões a partir de:

  • matéria
  • tópico
  • dificuldade
  • formato
  • instruções adicionais
  • dificuldades do aluno

Comportamento atual

  • se a API do Gemini estiver configurada, a geração usa o provedor
  • se não estiver configurada, ou se houver falha, o sistema usa questões mockadas
  • isso permite demonstrações sem custo de API

Exportação de PDF

A exportação em PDF está disponível no módulo de atividades.

Endpoint

GET /api/activities/{id}/export-pdf?includeAnswers=false

Comportamento

  • retorna application/pdf
  • força download com Content-Disposition
  • pode incluir ou ocultar gabarito
  • usa layout formatado para apresentação ao professor

Tratamento de Erros

A API possui tratamento global de exceções com respostas padronizadas.

Exemplo de erro

{
  "timestamp": "2026-03-31T12:06:53.5898956",
  "status": 400,
  "error": "Bad Request",
  "message": "Professor autenticado não encontrado"
}

Tipos tratados

  • 404 Not Found
  • 409 Conflict
  • 400 Bad Request
  • 500 Internal Server Error

Monitoramento

O projeto usa Spring Boot Actuator.

Endpoints expostos

  • /actuator/health
  • /actuator/info
  • /actuator/metrics
  • /actuator/prometheus

Regras

  • health e info podem ser públicos
  • demais endpoints podem exigir perfil/permissão de administrador

Rotas Principais

Autenticação

  • POST /api/auth/login
  • POST /api/auth/register/teacher

Alunos

  • POST /api/students
  • GET /api/students
  • GET /api/students/paginated
  • GET /api/students/{id}
  • GET /api/students/class/{classId}
  • GET /api/students/learning-gap/{subject}
  • PUT /api/students/{id}
  • DELETE /api/students/{id}
  • GET /api/students/{id}/performance
  • GET /api/students/{id}/attendance

Professores

  • POST /api/teachers
  • GET /api/teachers
  • GET /api/teachers/{id}
  • GET /api/teachers/email/{email}
  • PUT /api/teachers/{id}
  • DELETE /api/teachers/{id}
  • GET /api/teachers/subject/{subject}
  • GET /api/teachers/count

Turmas

  • POST /api/classrooms
  • GET /api/classrooms
  • GET /api/classrooms/paginated
  • GET /api/classrooms/{id}
  • GET /api/classrooms/teacher/{teacherId}
  • GET /api/classrooms/year/{year}
  • PUT /api/classrooms/{id}
  • DELETE /api/classrooms/{id}
  • POST /api/classrooms/{id}/enroll/{studentId}
  • DELETE /api/classrooms/{id}/unenroll/{studentId}
  • GET /api/classrooms/{id}/performance
  • GET /api/classrooms/{id}/attendance

Notas

  • POST /api/grades
  • GET /api/grades
  • GET /api/grades/paginated
  • GET /api/grades/{id}
  • GET /api/grades/student/{studentId}
  • GET /api/grades/classroom/{classroomId}
  • GET /api/grades/student/{studentId}/subject/{subject}
  • GET /api/grades/student/{studentId}/date-range
  • PUT /api/grades/{id}
  • DELETE /api/grades/{id}

Atividades

  • POST /api/activities
  • GET /api/activities
  • GET /api/activities/paginated
  • GET /api/activities/{id}
  • GET /api/activities/{id}/export-pdf
  • GET /api/activities/classroom/{classroomId}
  • GET /api/activities/student/{studentId}
  • GET /api/activities/filter
  • POST /api/activities/generate
  • PUT /api/activities/{id}
  • DELETE /api/activities/{id}

Exemplo de Fluxo de Uso

1. Fazer login

POST /api/auth/login

2. Copiar token JWT retornado

3. Usar token nas rotas protegidas

Authorization: Bearer <token>

4. Criar aluno, turma, nota ou atividade

5. Gerar atividade com IA

POST /api/activities/generate

6. Exportar atividade em PDF

GET /api/activities/{id}/export-pdf

Status Atual do Projeto

O projeto já possui:

  • autenticação JWT
  • documentação Swagger
  • CRUDs principais
  • integração com MongoDB
  • geração de atividades com fallback demo
  • exportação em PDF
  • tratamento global de erros
  • testes básicos de inicialização e PDF

Pontos que ainda podem evoluir:

  • testes mais completos de controller/service
  • melhor separação entre User e Teacher
  • auditoria de criação por usuário autenticado
  • integração com frontend
  • deploy em ambiente cloud

Licença

Este projeto está licenciado sob a MIT License.

Autor

Pedro Beltrão

Observação Final

Para integração com frontend, recomenda-se usar o Swagger como contrato principal da API:

Isso facilita geração de cliente HTTP, testes e alinhamento entre backend e frontend.

About

PlusEduc é uma API RESTful para gestão escolar com autenticação JWT, CRUD de alunos/turmas/notas, geração de atividades com IA (Google Gemini) e exportação de PDF. Construído com Spring Boot 3.4.1 e Java 21.

Topics

artificial-intelligenceeducationjavaspring-boot

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages