Study MVP

Aplicativo web local de estudos para CompTIA Security+ com banco de questoes, modos de quiz, estatisticas, revisao e flashcards. Feito com Next.js 14, TypeScript, React, Tailwind, Prisma e SQLite.

Requisitos

• Node.js 20+
• npm 10+
• SQLite via Prisma

Como rodar localmente

1. Instale dependencias:

npm install

2. Configure variaveis de ambiente:

cp .env.example .env

3. Gere o Prisma Client:

npx prisma generate

4. Aplique as migrations no SQLite local:

npx prisma migrate deploy

5. Opcional: popule dados de exemplo:

npm run seed

6. Suba a aplicacao:

npm run dev

7. Se o cache do Next ficar inconsistente, reinicie limpo:

npm run dev:clean

8. Opcional: abra Prisma Studio para inspecao do banco:

npx prisma studio

Scripts disponiveis

• npm run dev - inicia ambiente de desenvolvimento
• npm run dev:clean - limpa .next e inicia ambiente de desenvolvimento
• npm run build - build de producao
• npm run build:clean - limpa .next e executa build de producao
• npm run start - inicia build de producao
• npm run lint - executa ESLint
• npm run typecheck - executa tsc --noEmit
• npm run clean - remove o cache/artefatos gerados pelo Next em .next
• npm run seed - executa seed do Prisma
• npm test - executa testes unitarios/API com tsx --test
• npm run test:unit - alias para npm test

Rotas principais

• /study - tela principal de estudo, calendario, settings e modos de quiz
• /stats - estatisticas gerais, por dominio, por modo e sessoes recentes
• /review - revisao global com filtros, busca, respostas e explicacoes
• /review/session/:id - revisao detalhada de uma sessao de quiz
• /flashcards - cadastro, listagem, edicao e exclusao individual de flashcards
• /flashcards/review - revisao espacada de flashcards
• /questions - central integrada de banco de questoes
• /questions/new - cadastro manual direto de questao
• /questions/:id/edit - edicao direta de questao
• /questions/import - importacao em lote por texto
• /exams - criacao de simulados Security+ e simulados personalizados
• /exams/:id - responder simulado
• /exams/:id/review - revisar resultado, respostas e explicacoes
• /exams/history - historico de simulados realizados
• /dashboard - redireciona para /stats
• /train - redireciona para /study

APIs principais

• /api/study/quiz/start - inicia Quick 10, Timed Quiz, Level Up, Weakest Subject, Missed Questions, Build Your Own e Mock Exam
• /api/study/quiz/check-answer - valida resposta durante o quiz
• /api/study/quiz/submit - finaliza sessoes e calcula resultado no servidor
• /api/study/quiz/options - carrega opcoes e contadores para modais de quiz
• /api/questions - cria/lista questoes
• /api/questions/:id - edita ou inativa questoes
• /api/questions/import - pre-visualiza/importa questoes por texto; exclusao em massa esta desativada
• /api/review/flags - marca/desmarca questoes para revisao
• /api/flashcards - cria flashcards; exclusao em massa esta desativada
• /api/flashcards/:id - edita/exclui flashcard individual
• /api/flashcards/review - registra revisao SRS
• /api/exams - cria simulados
• /api/exams/:id/submit - finaliza simulado
• /api/dashboard/reset - mantido para compatibilidade de resets existentes

Navegacao atual

A navegacao principal fica enxuta:

• Study
• Stats
• Review
• Flashcards

O banco de questoes fica acessivel pela tela Study no botao Question Bank e tambem pela rota direta /questions.

Modos de quiz

• Quick 10: seleciona ate 10 questoes ativas e prontas, priorizando questoes novas.
• Timed Quiz: quiz com tempo configuravel.
• Level Up: progressao por dificuldade com estado persistente.
• Weakest Subject: escolhe o dominio mais fraco com base em desempenho.
• Missed Questions: revisa apenas questoes ainda marcadas como erradas.
• Build Your Own: permite montar quiz por dominio, dificuldade e tipo de questao.
• Mock Exam: monta simulado Security+ com distribuicao oficial quando possivel.

Todos os modos usam apenas questoes ativas e prontas para novos quizzes. Sessoes abandonadas nao devem contar como concluidas.

Regra atual do Level Up

O Level Up tem 3 niveis:

• Level 1: Easy
• Level 2: Medium
• Level 3: Hard

Rodada normal:

• 10/10: avanca para o proximo nivel.
• 9/10: entra em recovery round com 6 questoes.
• 8/10 ou menos: reinicia o mesmo nivel com 10 novas questoes.

Recovery round:

• 6/6: avanca para o proximo nivel.
• 5/6: repete recovery round com a nova questao errada obrigatoria.
• 4/6 ou menos: reinicia o nivel com rodada normal de 10 questoes.

No Level 3, uma rodada perfeita conclui o Level Up. O progresso fica em LevelUpProgress por dominio, e somente sessoes level-up finalizadas alteram essa progressao.

Question Bank

A central /questions permite:

• listar questoes
• buscar por enunciado
• filtrar por dominio
• filtrar por tema
• filtrar por dificuldade
• ver resposta correta e explicacao
• criar questao manualmente
• editar questao existente
• inativar/excluir de forma segura para novos quizzes
• importar varias questoes por texto
• ver contadores por dominio, dificuldade e itens sem classificacao

A classificacao principal das questoes agora e:

• dominio
• tema
• dificuldade

Tags livres podem continuar existindo para compatibilidade, mas nao sao a classificacao principal do app.

Importacao por texto

O importador aceita blocos em portugues ou ingles. Exemplo:

Enunciado:
Qual das opcoes descreve melhor o principio de menor privilegio?

A) Dar acesso administrativo a todos os usuarios.
B) Conceder apenas as permissoes necessarias para executar uma funcao.
C) Desabilitar autenticacao multifator.
D) Compartilhar senhas entre membros da equipe.

Resposta correta: B

Explicacao:
O principio de menor privilegio limita o acesso ao minimo necessario para reduzir risco.

Dominio: 1.0 General Security Concepts
Tema: Identity and Access Management
Dificuldade: facil

Tambem reconhece:

• Enunciado, Pergunta, Questao, Question
• Resposta correta, Gabarito, Correct answer, Answer
• Explicacao, Explanation, Rationale
• Dominio, Domain, Subject
• Tema, Topic, Theme
• Dificuldade, Difficulty

Separadores aceitos incluem linha em branco, ---, ###, Questao 1 e Question 1.

Normalizacao

Dominios aceitos e normalizados:

• 1.0 General Security Concepts
• 2.0 Threats, Vulnerabilities, and Mitigations
• 3.0 Security Architecture
• 4.0 Security Operations
• 5.0 Security Program Management and Oversight

Dificuldades aceitas e normalizadas:

• facil, facil, easy, beginner -> EASY
• medio, medio, medium, intermediate -> MEDIUM
• dificil, dificil, hard, advanced -> HARD

Dados e Prisma

Modelos principais:

• Question
• QuestionAttempt
• QuizSession
• QuestionReviewState
• LevelUpProgress
• Exam
• ExamQuestion
• Flashcard
• FlashcardReview
• DashboardCounterReset

Mudancas relevantes no schema:

• Question.isActive para soft delete/inativacao.
• QuizSession com status, modo, pontuacao, duracao, settings e relacao com tentativas.
• QuestionReviewState para flagged/missed sem apagar historico.
• LevelUpProgress para estado persistente do Level Up por dominio.
• Indices em campos usados por filtros e estatisticas: dominio, tema, dificuldade, ativo, tentativas, modo/status de sessao e datas.

Simulados

O Mock Exam tenta montar 90 questoes usando a divisao Security+:

• Domain 1: 11
• Domain 2: 20
• Domain 3: 16
• Domain 4: 25
• Domain 5: 18

Quando um dominio nao tem questoes suficientes, o plano balanceia com os dominios restantes e informa aviso.

Flashcards

Flashcards usam um SRS simples com ratings:

• AGAIN
• HARD
• GOOD
• EASY

A revisao atualiza intervalo, ease factor, contadores e proxima data. Exclusao em massa de flashcards/reviews foi desativada para proteger historico.

Seguranca e confiabilidade

• Score de quiz e calculado no servidor.
• API de submit valida modo, questoes e metadados criticos.
• Level Up valida dominio, dificuldade, tamanho da rodada, duplicatas e recovery question.
• Importacao tem modo preview antes de salvar.
• Importacao em massa nao deve duplicar quando a questao ja existe.
• Exclusao em massa de questoes e flashcards esta desativada.
• Backups locais *_bkp_* ficam ignorados pelo Git.
• tsconfig ignora backups para evitar falso erro de build.

Testes

A suite cobre:

• normalizacao de dominios
• normalizacao de dificuldades
• parser de importacao
• validacao de questoes
• selecao de Quick 10
• Level Up normal e recovery
• validacao server-side de submit Level Up
• Mock Exam e distribuicao oficial
• Weakest Subject
• Missed Questions
• Build Your Own
• estatisticas de estudo
• SRS dos flashcards
• APIs de importacao e bloqueio de exclusao em massa

Comandos usados para validacao:

npm test
npm run typecheck
npm run lint
npm run build

Ultima validacao local:

• npm test: 84 testes passando
• npm run typecheck: sem erros
• npm run lint: sem warnings/erros
• npm run build: build de producao concluido

Mudancas desde o ultimo commit

Ultimo commit analisado: 3c3ab0e feat: separar Clavis e corrigir dominios por materia.

Principais mudancas acumuladas:

• Reorganizacao da experiencia principal para tabs Study, Stats, Review e Flashcards.
• Criacao da tela /study com calendario, Quiz Settings e cards de modos de quiz.
• Redirecionamento de /train para /study.
• Redirecionamento de /dashboard para /stats.
• Criacao de /stats, /review e /review/session/:id.
• Criacao de APIs de quiz em /api/study/quiz/*.
• Criacao de StudyClient para executar quiz no frontend com modais e resumo final.
• Implementacao de Quick 10, Timed Quiz, Level Up, Weakest Subject, Missed Questions, Build Your Own e Mock Exam.
• Recriacao do Level Up com 3 niveis, recovery round e progresso persistente.
• Inclusao de validacao server-side especifica para Level Up.
• Centralizacao de configuracoes de estudo em lib/study-config.ts.
• Centralizacao de selecao/regras de quiz em lib/study-quiz.ts.
• Centralizacao de exibicao de modos em lib/study-display.ts.
• Criacao de estatisticas de estudo em lib/study-stats.ts.
• Question Bank reorganizado em /questions com contadores, abas internas, filtros e acoes principais.
• Cadastro manual de questao simplificado para dominio, tema e dificuldade.
• Edicao de questoes preservando historico antigo.
• Inativacao segura de questoes para novos quizzes.
• Importador por texto refeito com preview, avisos, erros e normalizacao.
• Parser reconhece aliases em portugues e ingles para enunciado, resposta, explicacao, dominio, tema e dificuldade.
• Normalizacao dos 5 dominios oficiais da Security+ em lib/domains.ts.
• Normalizacao de dificuldade para EASY, MEDIUM e HARD em lib/questions.ts.
• Remocao da rota antiga de tentativas /api/train-attempts.
• Adicao de QuizSession, QuestionReviewState e LevelUpProgress.
• Adicao de Question.isActive.
• Adicao de indices Prisma para filtros e consultas frequentes.
• Atualizacao do banco SQLite local versionado em prisma/dev.db.
• Simulados ajustados para usar apenas questoes ativas e dominios normalizados.
• Mock Exam validado para distribuicao 11/20/16/25/18.
• Stats e Review passam a ignorar sessoes abandonadas e lidar com sessoes antigas.
• Missed Questions usa estado ativo sem apagar historico.
• Flashcards receberam melhorias de UI, validacao e revisao.
• Exclusao em massa de questoes e flashcards foi desativada.
• Testes unitarios e de API foram ampliados.
• Scripts typecheck e test:unit foram adicionados.
• Backups locais foram excluidos da checagem TypeScript e ignorados no Git.
• Historico de migrations contem uma migration antiga de PBQ e uma migration posterior que remove essas tabelas; o app atual nao tem tela, fluxo ou API ativa de PBQ/Labs.

Solucao de problemas

Se aparecer erro como Cannot find module './948.js' vindo de .next/server/webpack-runtime.js, normalmente o cache de desenvolvimento do Next ficou inconsistente. Pare o servidor, rode npm run dev:clean e abra a aplicacao novamente.

Evite apagar a pasta .next enquanto npm run dev estiver em execucao, porque o servidor pode continuar apontando para chunks antigos que ja foram removidos.

Checklist manual

Use TESTING.md, quando existir, para validar persistencia de dados, importacoes e fluxos de estudo, simulado, review e flashcards.