trading-platform/docs/02-definicion-modulos/OQI-002-education/historias-usuario/US-EDU-006-realizar-quiz.md

id	title	type	status	priority	epic	story_points	created_date	updated_date
US-EDU-006	Realizar Quiz	User Story	Done	Alta	OQI-002	5	2025-12-05	2026-01-04

US-EDU-006: Realizar Quiz

Metadata

Campo	Valor
ID	US-EDU-006
Épica	OQI-002 - Módulo Educativo
Módulo	education
Prioridad	P1
Story Points	5
Sprint	Sprint 4
Estado	Pendiente
Asignado a	Por asignar

---

Historia de Usuario

Como usuario inscrito en un curso, quiero realizar quizzes interactivos al final de cada módulo, para validar mi conocimiento, recibir feedback y aprobar las evaluaciones requeridas.

Descripción Detallada

El usuario debe poder acceder a quizzes que evalúan el conocimiento adquirido en las lecciones. Debe poder responder preguntas de múltiple opción, navegar entre preguntas, revisar sus respuestas antes de enviar, recibir calificación inmediata, ver explicaciones de respuestas correctas/incorrectas, y reintentar si no aprobó (según intentos permitidos).

Mockups/Wireframes

[PANTALLA DE INTRODUCCIÓN AL QUIZ]
┌─────────────────────────────────────────────────────────────────┐
│  ← Volver al curso                                              │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│                    📝 QUIZ: FUNDAMENTOS DE FIBONACCI             │
│                                                                  │
│  Módulo 1: Introducción a Fibonacci                             │
│                                                                  │
│  ┌────────────────────────────────────────────────────────────┐ │
│  │  📊 Información del Quiz                                    │ │
│  │                                                             │ │
│  │  Preguntas: 10                                              │ │
│  │  Tiempo límite: 15 minutos                                  │ │
│  │  Puntuación para aprobar: 70%                               │ │
│  │  Intentos disponibles: 2 de 3                               │ │
│  │  Tipo: Evaluación                                           │ │
│  │                                                             │ │
│  │  ✓ Las preguntas están en orden aleatorio                  │ │
│  │  ✓ Verás tus respuestas al finalizar                       │ │
│  │  ✓ Puedes navegar libremente entre preguntas               │ │
│  └────────────────────────────────────────────────────────────┘ │
│                                                                  │
│              [🚀 Comenzar Quiz]                                 │
│                                                                  │
│  Intentos anteriores:                                           │
│  • Intento 1: 65% - Reprobado (hace 2 días)                    │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

[PANTALLA DE PREGUNTA]
┌─────────────────────────────────────────────────────────────────┐
│  Quiz: Fundamentos de Fibonacci           ⏱ 12:45 restantes    │
│  Pregunta 3 de 10                     ████████░░░░░░ 30%        │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  ¿Cuál es el nivel de retroceso de Fibonacci más utilizado?    │
│                                                                  │
│  ○ 23.6%                                                        │
│  ○ 38.2%                                                        │
│  ● 61.8%  ← Seleccionado                                        │
│  ○ 78.6%                                                        │
│                                                                  │
│  ┌────────────────────────────────────────────────────────────┐ │
│  │ [← Anterior]           [🚩 Marcar]          [Siguiente →]  │ │
│  └────────────────────────────────────────────────────────────┘ │
│                                                                  │
│  NAVEGADOR:                                                     │
│  [●1] [●2] [●3] [○4] [○5] [○6] [○7] [○8] [🚩9] [○10]         │
│   ↑    ↑    ↑   Sin  Sin  Sin  Sin  Sin  Marca Sin             │
│  Resp Resp Actual resp resp resp resp resp  da   resp          │
│                                                                  │
│                         [Finalizar Quiz]                        │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

[CONFIRMACIÓN DE ENVÍO]
┌─────────────────────────────────────────────────────────────────┐
│                   ⚠ ¿Estás seguro?                              │
│                                                                  │
│  Estás a punto de enviar tu quiz.                               │
│                                                                  │
│  Resumen:                                                        │
│  • Preguntas respondidas: 9 de 10                               │
│  • Preguntas sin responder: 1                                   │
│  • Preguntas marcadas para revisar: 1                           │
│                                                                  │
│  ⚠ Una vez enviado, no podrás cambiar tus respuestas.          │
│                                                                  │
│  [Cancelar]                            [Enviar Quiz]            │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

[RESULTADO - APROBADO]
┌─────────────────────────────────────────────────────────────────┐
│                        ✨ ✨ ✨                                  │
│                                                                  │
│                   ✅ ¡QUIZ APROBADO!                            │
│                                                                  │
│                      Puntuación: 85%                            │
│                     Preguntas correctas: 8.5/10                 │
│                                                                  │
│                     +30 XP ganados                              │
│                                                                  │
│  🎯 Desglose:                                                   │
│  • Preguntas correctas: 8                                       │
│  • Preguntas incorrectas: 2                                     │
│  • Puntuación requerida: 70%                                    │
│                                                                  │
│  Tiempo invertido: 10:32 de 15:00                              │
│  Intento: 2 de 3                                                │
│                                                                  │
│  [Ver respuestas y explicaciones]                               │
│  [Continuar al siguiente contenido →]                           │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

---

Criterios de Aceptación

Escenario 1: Ver introducción del quiz

DADO que el usuario está inscrito en el curso
CUANDO accede a una lección tipo quiz
ENTONCES se muestra pantalla de introducción
Y se muestra: número de preguntas, tiempo límite, puntuación para aprobar
Y se muestran intentos disponibles
Y se muestra historial de intentos anteriores (si existen)
Y se muestra botón "Comenzar Quiz"

Escenario 2: Comenzar quiz

DADO que el usuario está en la introducción del quiz
CUANDO hace click en "Comenzar Quiz"
ENTONCES se registra el inicio del intento en backend
Y se navega a la primera pregunta
Y se inicia el timer countdown
Y se carga el navegador de preguntas
Y se registra timestamp de inicio

Escenario 3: Responder pregunta de opción múltiple

DADO que el usuario está en una pregunta
CUANDO selecciona una opción
ENTONCES la opción se marca visualmente
Y la pregunta se marca como "respondida" en el navegador
Y puede cambiar su respuesta antes de enviar
Y la respuesta se guarda temporalmente en el estado

Escenario 4: Navegar entre preguntas

DADO que el usuario respondió la pregunta 3
CUANDO hace click en "Siguiente"
ENTONCES navega a la pregunta 4
Y su respuesta anterior se mantiene guardada
Y puede volver a pregunta 3 con "Anterior"
Y puede saltar a cualquier pregunta desde el navegador

Escenario 5: Marcar pregunta para revisión

DADO que el usuario está en una pregunta
Y tiene dudas sobre su respuesta
CUANDO hace click en "🚩 Marcar"
ENTONCES la pregunta se marca con bandera en el navegador
Y puede volver fácilmente a revisarla antes de enviar
Y puede desmarcarla con otro click

Escenario 6: Quiz con tiempo límite expira

DADO que el quiz tiene límite de 15 minutos
Y el usuario está respondiendo
CUANDO el timer llega a 0:00
ENTONCES el quiz se envía automáticamente
Y se muestra "Tiempo agotado"
Y se califica con las respuestas hasta el momento
Y preguntas sin responder cuentan como incorrectas

Escenario 7: Enviar quiz manualmente

DADO que el usuario respondió todas las preguntas
CUANDO hace click en "Finalizar Quiz"
ENTONCES se muestra modal de confirmación
Y muestra resumen: respondidas, sin responder, marcadas
Y al confirmar, se envía al backend
Y se calcula la puntuación
Y se muestra pantalla de resultados

Escenario 8: Aprobar quiz

DADO que el usuario envió el quiz
Y obtuvo 85% de puntuación
Y la puntuación mínima es 70%
ENTONCES se muestra "¡QUIZ APROBADO!"
Y se otorgan +30 XP
Y se marca la lección quiz como completada
Y se desbloquea siguiente contenido
Y se actualiza progreso del curso

Escenario 9: Reprobar quiz con intentos disponibles

DADO que el usuario obtuvo 65% (no aprobó)
Y quedan 2 intentos disponibles
ENTONCES se muestra "Quiz Reprobado"
Y se muestra puntuación obtenida
Y se muestra "Intentos restantes: 2"
Y se muestra botón "Reintentar"
Y NO se desbloquea siguiente contenido
Y NO se otorga XP

Escenario 10: Reprobar quiz sin intentos

DADO que el usuario agotó todos los intentos
Y no aprobó el quiz
ENTONCES se muestra mensaje "Sin intentos disponibles"
Y se sugiere "Repasa las lecciones y contacta a soporte"
Y el siguiente contenido permanece bloqueado
Y se registra el bloqueo para seguimiento

Escenario 11: Ver explicaciones de respuestas

DADO que el usuario completó el quiz
CUANDO hace click en "Ver respuestas y explicaciones"
ENTONCES se muestran todas las preguntas
Y se destacan respuestas correctas en verde
Y se destacan respuestas incorrectas en rojo
Y se muestra la respuesta correcta
Y se muestra explicación detallada de cada respuesta
Y se sugieren lecciones relacionadas para repasar

Escenario 12: Reintentar quiz

DADO que el usuario reprobó el quiz
Y tiene intentos disponibles
CUANDO hace click en "Reintentar"
ENTONCES se inicia un nuevo intento
Y las preguntas pueden estar en diferente orden
Y las opciones pueden estar en diferente orden
Y sus respuestas anteriores NO están pre-seleccionadas
Y el contador de intentos se decrementa

Criterios Adicionales

• Auto-save de respuestas cada 30s (protección contra pérdida)
• Advertencia antes de salir de la página sin enviar
• Modo revisión: ver quiz aprobado sin poder cambiar respuestas
• Estadísticas del quiz: % de aprobación, tiempo promedio
• Preguntas con imágenes embebidas
• Tipo de pregunta: multiple select (varias correctas)
• Puntuación parcial en multiple select

---

Tareas Técnicas

Database:

• DB-EDU-015: Tabla education.quizzes
• DB-EDU-016: Tabla education.questions (FK a quiz)
• DB-EDU-017: Tabla education.question_options
• DB-EDU-018: Tabla education.quiz_attempts
• DB-EDU-019: Tabla education.quiz_answers (respuestas del usuario)

Backend:

• BE-EDU-039: Endpoint GET /education/quizzes/:id
• BE-EDU-040: Endpoint POST /education/quizzes/:id/start
• BE-EDU-041: Endpoint POST /education/quizzes/:id/submit
• BE-EDU-042: Endpoint GET /education/quizzes/:id/attempts
• BE-EDU-043: Endpoint GET /education/quizzes/:id/results/:attemptId
• BE-EDU-044: Implementar QuizService.gradeAttempt()
• BE-EDU-045: Implementar shuffle de preguntas y opciones
• BE-EDU-046: Validar intentos disponibles
• BE-EDU-047: Implementar timer y auto-submit
• BE-EDU-048: NO devolver respuestas correctas en GET (seguridad)

Frontend:

• FE-EDU-048: Crear QuizIntroPage.tsx
• FE-EDU-049: Crear QuizPlayerPage.tsx
• FE-EDU-050: Crear componente QuestionRenderer.tsx
• FE-EDU-051: Crear componente QuizNavigator.tsx (minimap)
• FE-EDU-052: Crear componente QuizTimer.tsx
• FE-EDU-053: Crear QuizResultsPage.tsx
• FE-EDU-054: Crear componente AnswerExplanation.tsx
• FE-EDU-055: Modal de confirmación de envío
• FE-EDU-056: Auto-save de respuestas cada 30s
• FE-EDU-057: Advertencia antes de salir (window.onbeforeunload)
• FE-EDU-058: Implementar quizStore (Zustand)
• FE-EDU-059: Animación de celebración al aprobar

Tests:

• TEST-EDU-021: Test calificación de quiz
• TEST-EDU-022: Test aprobar quiz otorga XP
• TEST-EDU-023: Test auto-submit cuando expira tiempo
• TEST-EDU-024: Test límite de intentos
• TEST-EDU-025: Test E2E realizar quiz completo

---

Dependencias

Depende de:

• US-EDU-003: Iniciar lección - Estado: Pendiente
• RF-EDU-004: Sistema de quizzes

Bloquea:

• US-EDU-005: Completar lección
• US-EDU-007: Ver progreso

---

Notas Técnicas

Endpoint GET /quizzes/:id (SIN respuestas correctas):

{
  quiz: {
    id: "quiz-1",
    title: "Fundamentos de Fibonacci",
    description: "Evalúa tu conocimiento...",
    timeLimit: 15, // minutos
    passingScore: 70, // 0-100
    maxAttempts: 3,
    questionCount: 10,
    totalPoints: 10,
    shuffleQuestions: true,
    shuffleOptions: true,
    mode: "assessment",

    questions: [
      {
        id: "q-1",
        question: "¿Cuál es el nivel más utilizado?",
        type: "multiple_choice",
        points: 1,
        options: [
          { id: "opt-1", text: "23.6%" },
          { id: "opt-2", text: "38.2%" },
          { id: "opt-3", text: "61.8%" },
          { id: "opt-4", text: "78.6%" }
        ]
        // NO incluir isCorrect en GET
      }
    ],

    userAttempts: [
      {
        attemptNumber: 1,
        score: 65,
        passed: false,
        submittedAt: "2025-12-03T10:30:00Z"
      }
    ],
    attemptsRemaining: 2
  }
}

Endpoint POST /quizzes/:id/submit:

// Request
{
  answers: {
    "q-1": "opt-3",
    "q-2": "opt-1",
    "q-3": ["opt-2", "opt-4"], // Multiple select
    // ...
  },
  timeSpent: 632 // segundos
}

// Response
{
  attempt: {
    id: "attempt-uuid",
    quizId: "quiz-1",
    attemptNumber: 2,
    score: 85,
    passed: true,
    pointsEarned: 8.5,
    totalPoints: 10,
    submittedAt: "2025-12-05T16:45:00Z"
  },
  rewards: {
    xpEarned: 30,
    bonusXP: 20, // Si es 100%
    totalXP: 50
  },
  answers: [
    {
      questionId: "q-1",
      userAnswer: "opt-3",
      correctAnswer: "opt-3",
      isCorrect: true,
      pointsEarned: 1,
      explanation: "61.8% es el nivel dorado..."
    }
    // ...
  ],
  attemptsRemaining: 1,
  canRetake: true
}

Reglas de calificación:

• Multiple choice: 1 punto si es correcta, 0 si no
• Multiple select: puntos parciales (0.5 si acierta 2 de 4)
• True/False: 1 punto si es correcta
• Sin responder: 0 puntos

Entidades/Tablas:

• education.quizzes
• education.questions
• education.question_options
• education.quiz_attempts
• education.quiz_answers

---

Definition of Ready (DoR)

• Historia claramente escrita
• Criterios de aceptación definidos
• Story points estimados
• Dependencias identificadas
• Sin bloqueadores
• Diseño/mockup disponible
• API spec disponible

Definition of Done (DoD)

• Código implementado según criterios
• Tests unitarios escritos y pasando
• Tests de integración pasando
• Code review aprobado
• Documentación actualizada
• QA aprobado
• Desplegado en ambiente de pruebas

---

Historial de Cambios

Fecha	Cambio	Autor
2025-12-05	Creación	Requirements-Analyst

---

Creada por: Requirements-Analyst Fecha: 2025-12-05 Última actualización: 2025-12-05