Quizzes y Evaluaciones

Sistema completo de evaluaciones que permite a los administradores crear quizzes de opción múltiple y a los estudiantes demostrar su aprendizaje.

Vista Rápida

• Admins: Crean y gestionan quizzes desde /admin/courses/:courseId/quizzes
• Estudiantes: Toman quizzes desde la página de aprendizaje del curso
• Intentos: Ilimitados para practicar y mejorar
• Aprobación: Configurable (default 70%)

---

Setup para Desarrolladores

Configuración Inicial

Si estás configurando el sistema de quizzes por primera vez:

Opción A: Base de Datos Nueva (Recomendado)

cd app/

# Resetear database y aplicar todas las migraciones
wasp db reset

# Poblar con datos de prueba (cursos + quizzes + usuarios)
wasp db seed seedAllDummyData

Opción B: Base de Datos Existente

cd app/

# Aplicar solo la migración de quizzes
wasp db migrate-dev

# Opcionalmente, agregar quizzes de prueba
wasp db seed seedDummyQuizzes

Tablas Creadas

La migración crea 4 tablas:

• Quiz - Definiciones de quizzes
• QuizQuestion - Preguntas de cada quiz
• QuizAnswer - Opciones de respuesta
• QuizAttempt - Intentos de usuarios y puntuaciones

Datos de Prueba

El seed seedAllDummyData o seedDummyQuizzes crea:

• 2 quizzes por curso (primeros 2 cursos):
  • “Quiz de Introducción” - Vinculado a la primera lección (3 preguntas)
  • “Examen Final” - Examen final sin lección específica (2 preguntas)

Importante para Admin

La gestión de quizzes solo está disponible para cursos GUARDADOS, no para nuevos. Primero debes crear y guardar un curso antes de agregar quizzes.

---

Para Administradores

Cómo Crear un Quiz

Paso 1: Acceder a la Gestión de Quizzes

1. Inicia sesión como administrador
2. Ve a Admin → Cursos (/admin/courses)
3. Haz clic en “Editar” en el curso donde quieres agregar el quiz
4. En la página de edición del curso, haz clic en el botón “Quizzes”
   • O navega directamente a /admin/courses/:courseId/quizzes

Paso 2: Crear Nuevo Quiz

1. Haz clic en ”+ Crear Quiz”
2. Completa el formulario básico:

Campo	Descripción	Ejemplo
Título	Nombre del quiz (requerido)	“Quiz de Introducción”
Descripción	Explicación opcional del contenido	”Evalúa conceptos básicos”
Orden	Posición en el curso (1, 2, 3…)	1
Lección Asociada	Vincular a lección específica (opcional)	“Lección 1: Introducción”
Puntuación	% mínimo para aprobar (0-100)	70 (default)
Límite de Tiempo	Minutos permitidos (vacío = sin límite)	15 o dejar vacío
Es Requerido	¿Obligatorio para avanzar? (toggle)	☑ / ☐
Es Examen Final	¿Marcar como examen final del curso?	☐ (solo para examen final)

Paso 3: Agregar Preguntas

Después de completar los datos básicos, ve a la sección “Preguntas”:

1. Haz clic en ”+ Agregar Pregunta”
2. Para cada pregunta, completa:

Campo	Descripción	Ejemplo
Pregunta	Texto de la pregunta (requerido)	“¿Qué es Data Engineering?”
Explicación	Explicación mostrada tras responder	”Data Engineering se enfoca en…”

3. Agregar Respuestas (mínimo 2):

   • Texto de la respuesta
   • Toggle “Correcta” para marcar la respuesta correcta
   • Mínimo 2 respuestas, máximo ilimitado
   • Debe haber al menos UNA respuesta correcta por pregunta

4. Puedes eliminar respuestas haciendo clic en el ícono 🗑️ (mínimo 2 deben permanecer)

Paso 4: Guardar el Quiz

1. Haz clic en “Guardar Quiz”

2. El sistema validará:

   • ✅ Título no vacío
   • ✅ Al menos 1 pregunta
   • ✅ Cada pregunta tiene al menos 2 respuestas
   • ✅ Cada pregunta tiene al menos 1 respuesta correcta
   • ✅ Todas las respuestas tienen texto

3. Si hay errores, aparecerá un mensaje rojo con la validación fallida

4. Si todo está correcto, verás “Quiz guardado correctamente”

---

Ejemplo Completo: Quiz de Introducción

📝 Título: Quiz de Introducción a Python
📄 Descripción: Evalúa tu comprensión de los conceptos básicos de Python
🔢 Orden: 1
📚 Lección: Lección 1 - Introducción a Python
✅ Puntuación: 70%
⏱️ Tiempo límite: (sin límite)
🔒 Requerido: Sí
🏆 Examen final: No

❓ Pregunta 1:
   "¿Qué es Python?"
   ℹ️ Explicación: "Python es un lenguaje de programación interpretado..."

   Respuestas:
   ☑️ "Un lenguaje de programación interpretado" (CORRECTA)
   ☐ "Una base de datos"
   ☐ "Un framework web"
   ☐ "Un editor de texto"

❓ Pregunta 2:
   "¿Cuál es la extensión de archivos Python?"
   ℹ️ Explicación: ".py es la extensión estándar para archivos Python"

   Respuestas:
   ☐ ".python"
   ☑️ ".py" (CORRECTA)
   ☐ ".pt"
   ☐ ".pyt"

❓ Pregunta 3:
   "¿Python es case-sensitive?"

   Respuestas:
   ☑️ "Sí" (CORRECTA)
   ☐ "No"

---

Cómo Editar un Quiz

1. Ve a /admin/courses/:courseId/quizzes

2. En la lista de quizzes, haz clic en el botón ✏️ Editar

3. Modifica cualquier campo:

   • Detalles del quiz: título, descripción, configuración
   • Preguntas existentes: edita texto, explicación, respuestas
   • Agregar nuevas preguntas: botón ”+ Agregar Pregunta”
   • Eliminar preguntas: botón 🗑️ en cada pregunta

4. Haz clic en “Guardar Quiz”

Atención

Los cambios afectan todos los intentos futuros. Los intentos anteriores guardan las respuestas originales.

---

Cómo Eliminar un Quiz

1. Ve a /admin/courses/:courseId/quizzes
2. Haz clic en el botón 🗑️ junto al quiz
3. Confirma la eliminación

Irreversible

Eliminar un quiz también elimina:

• Todas las preguntas y respuestas
• Todos los intentos de usuarios
• Esta acción NO se puede deshacer

---

Ver Estadísticas

En la lista de quizzes (/admin/courses/:courseId/quizzes), cada quiz muestra:

Métrica	Descripción
Preguntas	Número de preguntas en el quiz
Intentos	Total de intentos de usuarios
% Aprobación	Porcentaje para aprobar
Orden	Posición en el curso

---

Tipos de Quizzes Recomendados

1. Quiz de Lección (Knowledge Check)

• Lección asociada: Sí
• Preguntas: 3-5
• Tiempo límite: Sin límite
• Requerido: No
• Finalidad: Reforzar conceptos de la lección

2. Quiz de Módulo

• Lección asociada: No (o última del módulo)
• Preguntas: 8-12
• Tiempo límite: 20 minutos
• Requerido: Sí
• Finalidad: Evaluar comprensión del módulo completo

3. Examen Final

• Lección asociada: No
• Preguntas: 15-25
• Tiempo límite: 45-60 minutos
• Requerido: Sí
• Es Examen Final: ☑️
• Puntuación: 80%
• Finalidad: Certificar dominio del curso

---

Mejores Prácticas

Diseño de Preguntas

✅ Buenas Preguntas

• Claras y concisas
• Evalúan comprensión, no memorización
• Una sola respuesta correcta clara
• Distractores plausibles pero incorrectos

❌ Evitar

• Preguntas ambiguas o confusas
• Truco questions (muy similares entre sí)
• Respuestas obvias o ridículas
• Preguntas de “doble negativo”

Ejemplos

❌ Mala Pregunta:

"¿No es cierto que Python no necesita punto y coma?"
a) No
b) Sí
c) Tal vez
d) Depende

✅ Buena Pregunta:

"¿Qué símbolo se usa para comentarios en Python?"
a) //
b) /* */
c) #
d) --

Número de Respuestas

• Mínimo: 2 respuestas (pero se recomienda 4)
• Óptimo: 4 respuestas
• Máximo: Sin límite, pero 6+ puede confundir

Tiempo Límite

Tipo de Pregunta	Tiempo Recomendado
Opción múltiple basic	30-45 segundos
Análisis de código	60-90 segundos
Quiz completo (10Q)	15 minutos
Examen final (20Q)	45-60 minutos

---

Para Estudiantes

Cómo Tomar un Quiz

Paso 1: Acceder al Quiz

1. Inicia sesión en tu cuenta
2. Ve a tu curso en Mis Cursos o desde el catálogo
3. Haz clic en “Continuar Aprendiendo” o “Ir al Curso”
4. En la página de aprendizaje, haz clic en la pestaña “Quizzes” en el sidebar

Acceso Rápido

Los quizzes solo están disponibles para cursos en los que estás inscrito o si tienes suscripción activa.

Paso 2: Ver Detalles del Quiz

Antes de comenzar, verás:

Información	Ejemplo
Título	”Quiz de Python”
Descripción	”Evalúa conceptos”
Preguntas	10 preguntas
% Aprobación	70%
Tiempo límite	15 minutos o ∞
Tu mejor intento	85% ✅ (si ya tomaste)

Haz clic en “Comenzar Quiz” o “Reintentar” (si ya lo tomaste).

Paso 3: Responder Preguntas

1. Lee cada pregunta cuidadosamente

2. Selecciona UNA respuesta haciendo clic en el radio button

3. Navega con los botones:

   • ← Anterior: Regresar a la pregunta anterior
   • Siguiente →: Ir a la siguiente pregunta

4. Temporizador (si hay límite):

   • Se muestra en la esquina superior derecha
   • ⏱️ 14:32 restantes
   • Alerta cuando queden 2 minutos
   • Auto-envío cuando se acabe el tiempo

5. Progreso: Indicador visual de preguntas respondidas

   • “Pregunta 3 de 10”

Paso 4: Enviar el Quiz

1. Después de responder todas las preguntas, aparece el botón “Enviar Quiz”
2. Confirma el envío (no se puede cambiar después)
3. El quiz se califica automáticamente

Paso 5: Ver Resultados

Inmediatamente después de enviar, verás:

Sección	Contenido
Puntuación	Tu puntaje (%) y si aprobaste
Estadísticas	Correctas/Incorrectas, Tiempo empleado
Detalles	Pregunta por pregunta con:
	- Tu respuesta
	- Respuesta correcta
	- Explicación (si existe)
	- ✅ / ❌ indicador
Mejor intento	Tu mejor puntaje histórico

---

Ejemplo de Resultados

🎉 ¡Felicidades! Aprobaste el quiz

Tu Puntuación: 85% ✅
Puntuación Mínima: 70%

📊 Estadísticas:
   ✅ Correctas: 17/20
   ❌ Incorrectas: 3/20
   ⏱️ Tiempo: 12 min 34 seg

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

❓ Pregunta 1: ¿Qué es Python?
   Tu respuesta: "Un lenguaje de programación" ✅
   ℹ️ Correcto! Python es un lenguaje interpretado...

❓ Pregunta 2: ¿Qué es un diccionario en Python?
   Tu respuesta: "Una lista" ❌
   ✅ Respuesta correcta: "Una estructura clave-valor"
   ℹ️ Un diccionario (dict) almacena pares clave-valor...

[... resto de preguntas ...]

[🔄 Reintentar Quiz]  [← Volver al Curso]

---

Reintentar un Quiz

Los quizzes se pueden tomar ILIMITADAMENTE:

1. Haz clic en “Reintentar Quiz” en la página de resultados
2. O vuelve a la lista de quizzes y selecciona el mismo quiz
3. Tu mejor puntaje se guarda automáticamente
4. Puedes ver el historial de intentos en tu perfil

Estrategia de Estudio

1. Primer intento: Evalúa tu conocimiento actual
2. Revisa las explicaciones de respuestas incorrectas
3. Repasa el material del curso
4. Segundo intento: Demuestra tu mejora

---

Integración con el Sistema

Donde Aparecen los Quizzes

Ubicación	Vista
LearnPage (Sidebar)	Tab “Quizzes” con lista de quizzes
QuizCard	Card con info, mejor puntaje, botón
QuizPage	Página completa para tomar el quiz
QuizResults	Página de resultados detallados
Admin Quiz List	Lista de quizzes con estadísticas
Admin Quiz Form	Editor completo de quiz

Flujo Completo

┌─────────────────────────────────────────────────────────────┐
│ Admin crea quiz en /admin/courses/:id/quizzes               │
│   ↓                                                           │
│ Quiz aparece en LearnPage → Tab "Quizzes"                    │
│   ↓                                                           │
│ Estudiante ve QuizCard con descripción y mejor puntaje       │
│   ↓                                                           │
│ Click "Tomar Quiz" → navega a /quiz/:quizId                   │
│   ↓                                                           │
│ QuizPage carga preguntas con QuizComponent                    │
│   ↓                                                           │
│ Estudiante responde y envía → submitQuizAttempt              │
│   ↓                                                           │
│ QuizResults muestra puntuación, feedback, explicaciones       │
│   ↓                                                           │
│ Opción de reintentar o volver al curso                       │
└─────────────────────────────────────────────────────────────┘

---

Operaciones del Sistema

Queries (Lectura)

Query	Descripción	Uso
getCourseQuizzes	Obtiene quizzes de un curso (estudiante)	LearnPage sidebar
getQuizById	Obtiene quiz con preguntas	QuizPage
getQuizAttempts	Obtiene intentos de usuario	Historial, mejor score
getAdminQuizzes	Obtiene quizzes (admin con más detalles)	Admin quiz list
getAdminQuizById	Obtiene quiz para edición	Admin quiz form

Actions (Escritura)

Action	Descripción	Uso
createQuiz	Crea nuevo quiz	Admin form
updateQuiz	Actualiza quiz existente	Admin form
deleteQuiz	Elimina quiz y dependencias	Admin list
createQuizQuestion	Agrega pregunta con respuestas	Admin form
updateQuizQuestion	Actualiza pregunta	Admin form
deleteQuizQuestion	Elimina pregunta	Admin form
submitQuizAttempt	Registra intento y califica	QuizPage (estudiante)

---

Modelos de Base de Datos

Quiz

{
  id: number
  courseId: number
  lessonId?: number | null       // null = examen final
  title: string
  description?: string
  order: number
  passingScore: number           // default: 70
  timeLimit?: number | null      // segundos
  isRequired: boolean            // default: false
  isFinalExam: boolean           // default: false
  questions: QuizQuestion[]
  attempts: QuizAttempt[]
}

QuizQuestion

{
  id: number
  quizId: number
  question: string
  order: number
  explanation?: string           // Mostrado tras responder
  answers: QuizAnswer[]
}

QuizAnswer

{
  id: number;
  questionId: number;
  answer: string;
  isCorrect: boolean;
  order: number;
}

QuizAttempt

{
  id: number
  userId: string
  quizId: number
  score: number                  // 0-100
  passed: boolean                // score >= passingScore
  timeSpent?: number             // segundos
  answers: string                // JSON: { questionId: answerId }
  createdAt: Date
}

---

Seed Data (Desarrollo)

Para poblar la base de datos con quizzes de ejemplo:

wasp db seed seedDummyQuizzes

Esto crea:

• 4 quizzes en los primeros 2 cursos
• 2 quizzes por curso:
  1. “Quiz de Introducción” (3 preguntas, 70% passing)
  2. “Examen Final” (2 preguntas, 80% passing)

---

Troubleshooting

Problema: Error 404 en /admin/courses/:courseId/quizzes

Causa: Problema de orden de rutas (ya resuelto)

Solución:

1. Asegúrate de tener la versión más reciente del código
2. REINICIA el servidor Wasp (crítico - las rutas se compilan al inicio):

   # Detener el servidor (Ctrl+C)
   wasp start

3. Las rutas de quiz ahora tienen prioridad sobre la ruta genérica de edición de curso

Problema: No encuentro “Gestión de Quizzes” en la página de edición de curso

Causa: La sección de quizzes solo aparece para cursos GUARDADOS, no para nuevos

Solución:

1. Primero crea y guarda un curso (o usa uno existente)
2. Luego haz clic en “Editar” en ese curso
3. Desplázate hacia abajo - la sección “Gestión de Quizzes” aparece DEBAJO de “Lecciones”
4. Verás un botón “Agregar Quiz” ahí

Problema: Seed falla con “table Quiz does not exist”

Causa: La migración de quizzes no se ha aplicado

Solución:

# Aplicar migración primero
wasp db migrate-dev

# Luego hacer seed
wasp db seed seedAllDummyData

# O usar reset que hace todo automáticamente
wasp db reset

Problema: “No veo el tab de Quizzes” en la página de aprendizaje

Soluciones:

1. Verifica que estés inscrito en el curso o tengas suscripción activa
2. Revisa que el curso tenga quizzes creados (como admin)
3. Reinicia el dev server: wasp start
4. Limpia la caché del navegador (Ctrl+Shift+R)

Problema: “Error 500 al crear quiz”

Soluciones:

1. Verifica que las tablas Quiz existan en la DB:

   # Conectarse a la DB y listar tablas
   docker exec -i wasp-dev-db-[nombre] psql -U postgresWaspDevUser -d [db-name] -c "\dt"

2. Si faltan tablas, ejecuta: wasp db migrate-dev
3. Revisa validaciones del formulario:
   • Título no vacío
   • Al menos 1 pregunta
   • Cada pregunta tiene ≥2 respuestas
   • Cada pregunta tiene ≥1 respuesta correcta

Problema: “Las preguntas no se guardan”

Soluciones:

1. Asegúrate de que cada pregunta cumple:
   • ✅ Al menos 2 respuestas
   • ✅ Al menos 1 respuesta marcada como correcta
   • ✅ Texto en todas las respuestas (no vacías)
2. Revisa la consola del navegador (F12) para errores JavaScript
3. Verifica que no haya errores de red en la pestaña Network

Problema: Errores de compilación TypeScript

Ya resueltos en la versión actual:

• ✅ Componente radio-group agregado
• ✅ Manejo de courseId undefined corregido
• ✅ Manejo de quizId undefined corregido
• ✅ Migrado de useHistory a useNavigate (React Router v6)
• ✅ Tipos de relación lesson nullable arreglados

Si ves errores de compilación, asegúrate de tener la última versión del código.

Problema: “No puedo crear quiz como admin”

Soluciones:

1. Verifica que estés autenticado como admin:
   • Email: admin@talentbricks.ai
   • Password: AdminPass123!
2. El curso debe estar guardado (no puede ser “nuevo”)
3. Si acabas de actualizar el código con corrección de rutas, reinicia Wasp

Problema: “Los quizzes no aparecen en cursos”

Soluciones:

1. Ejecuta el seed: wasp db seed seedAllDummyData
2. Verifica que los cursos existan primero
3. Revisa que el usuario esté inscrito o tenga suscripción activa
4. Comprueba en la tabla Quiz que existan registros:

   docker exec -i wasp-dev-db-[nombre] psql -U postgresWaspDevUser -d [db-name] -c "SELECT * FROM \"Quiz\";"

---

Próximas Mejoras

Funcionalidades planeadas para futuras versiones:

• Drag & drop para reordenar preguntas
• Tipos de pregunta adicionales (verdadero/falso, llenar espacios)
• Banco de preguntas reutilizables
• Exportar resultados a CSV
• Análisis de preguntas (% de aciertos por pregunta)
• Randomizar orden de preguntas y respuestas
• Preguntas con imágenes
• Certificado requerido: aprobar X quizzes

---

Recursos Adicionales

• Código fuente: app/src/admin/dashboards/quizzes/ y app/src/courses/components/Quiz*.tsx
• Operaciones: app/src/admin/operations.ts (admin) y app/src/courses/operations.ts (estudiante)
• Schema: app/schema.prisma (modelos Quiz, QuizQuestion, QuizAnswer, QuizAttempt)
• Rutas: Declaradas en app/main.wasp