eTecTrilha API v1.0.0

API REST do eTecTrilha — app gamificado de estudos para o Vestibulinho ETEC. Autenticação via sessão NextAuth (cookie). Rotas /admin exigem papel ADMIN.

Especificação OpenAPI 3.0 completa em /api/openapi.json — importe no Swagger UI, Postman ou Insomnia.

Auth

Cadastro e login

post/api/auth/register

Cadastra usuário com e-mail e senha

get/api/auth/signin

Fluxo de login NextAuth (Google e credenciais)

Perfil

Dados do usuário logado

get/api/me

Resumo do usuário: XP, nível, vidas, streak, precisão, revisões pendentes

patch/api/me

Atualiza nome e preferência de som

Jornada

Disciplinas, módulos e fases

get/api/journey

Jornada completa: disciplinas → módulos → fases, com progresso e bloqueios

get/api/phases/{id}

Questões de uma fase (sem gabarito)

post/api/phases/{id}/complete

Registra conclusão de fase (+100 XP na primeira conclusão com ≥70%)

Estudo

Respostas, revisão espaçada e desafio diário

post/api/answers

Responde uma questão — retorna gabarito, explicação, XP, vidas e conquistas

Regras: +10 XP por acerto (dobro no desafio diário); +50 XP a cada 5 acertos seguidos (campo combo); errar em fase/desafio custa 1 vida; erros entram na revisão espaçada (1, 3, 7, 15, 30 dias).

get/api/review

Questões erradas vencidas para revisar (repetição espaçada)

get/api/challenge

Desafio diário (10 questões, XP em dobro) e status do dia

post/api/challenge/complete

Registra a conclusão do desafio diário

Simulados

get/api/exams

Lista os simulados do usuário

post/api/exams

Cria um simulado com filtros (ano, disciplina, aleatório)

get/api/exams/{id}

Detalhe do simulado (gabarito incluído apenas após finalizar)

post/api/exams/{id}/submit

Finaliza o simulado: nota, acertos, erros, tempo, percentil e análise por disciplina

Estatísticas

get/api/stats

Dashboard: acertos por disciplina, evolução semanal, mapa de calor, tempo estudado

get/api/ranking

Ranking semanal, mensal ou geral

get/api/achievements

Conquistas (todas + desbloqueadas)

Admin

Gestão do banco de questões

get/api/admin/questions

Lista questões com filtros e paginação

post/api/admin/questions

Cadastra uma questão

put/api/admin/questions/{id}

Edita uma questão

delete/api/admin/questions/{id}

Exclui uma questão

post/api/admin/import

Importa questões em massa (JSON ou CSV, até 10.000 por chamada)

Cabeçalhos aceitos (flexíveis): ano, semestre, disciplina, tema, enunciado, a, b, c, d, e, correta/gabarito, explicacao, dificuldade, tempo_medio.