workspace-v1/projects/gamilit/docs/01-fase-alcance-inicial/EAI-002-actividades/requerimientos/RF-EDU-002-niveles-dificultad.md

RF-EDU-002: Niveles de Dificultad de Ejercicios

📋 Metadata

Campo	Valor
ID	RF-EDU-002
Módulo	03 - Contenido Educativo
Título	Niveles de Dificultad y Progresión Adaptativa
Prioridad	Alta
Estado	✅ Implementado
Versión	1.0
Fecha Creación	2025-11-07
Última Actualización	2025-11-07
Autor	Database Team, Pedagogical Team
Stakeholders	Product Owner, Content Team, Teachers, Students

---

🔗 Referencias

Implementación DDL

🗄️ ENUM Canónico:

• Ubicación: apps/database/ddl/00-prerequisites.sql:50-58
• Tipo: educational_content.difficulty_level
• Valores: beginner, elementary, pre_intermediate, intermediate, upper_intermediate, advanced, proficient, native

🗄️ Tablas Relacionadas:

1. educational_content.exercises

   • Columna: difficulty (ENUM difficulty_level)
   • Propósito: Nivel de dificultad del ejercicio

2. educational_content.difficulty_parameters

   • Ubicación: apps/database/ddl/schemas/educational_content/tables/difficulty_parameters.sql:1-35
   • Propósito: Parámetros que definen cada nivel de dificultad
   • Columnas clave:
     • difficulty_level (ENUM)
     • vocabulary_complexity (1-10)
     • grammar_complexity (1-10)
     • sentence_length_avg (palabras)
     • time_limit_multiplier (FLOAT)

Especificación Técnica

📘 Documento ET Relacionado:

• ET-EDU-002: Implementación de Niveles de Dificultad

Documentos Relacionados

• RF-EDU-001: Mecánicas de Ejercicios - Ejercicios con dificultad variable
• RF-EDU-003: Taxonomía de Bloom - Complejidad cognitiva
• RF-GAM-001: Sistema de XP - XP por dificultad
• RF-PRG-001: Estados de Progreso - Desbloqueo progresivo
• MAPEO: Requerimientos → Implementación

---

📖 Descripción General

Propósito

El Sistema de Niveles de Dificultad clasifica los ejercicios en 8 niveles progresivos que van desde principiante absoluto hasta nivel nativo. Este sistema:

• Proporciona progresión pedagógica clara
• Adapta recompensas según dificultad (XP, ML Coins)
• Personaliza tiempo límite por nivel
• Guía el desbloqueo secuencial de contenido
• Genera estadísticas de desempeño por nivel

Marco Conceptual

Los niveles siguen el Marco Común Europeo de Referencia (CEFR) adaptado al contexto de lengua maya:

Principiante → Elemental → Pre-intermedio → Intermedio → Intermedio Alto → Avanzado → Proficiente → Nativo
    A1           A2             B1              B2               C1               C2          C2+         Nativo

---

⚙️ Los 8 Niveles de Dificultad

1. Beginner (Principiante) - A1

Perfil del Estudiante:

• Primer contacto con el idioma maya
• Sin conocimientos previos
• Edad: 6-8 años o adultos principiantes

Características de Ejercicios:

Aspecto	Parámetros
Vocabulario	10-50 palabras conocidas
Gramática	Solo presente simple, estructuras básicas
Longitud de Oraciones	3-5 palabras
Complejidad Cognitiva	Recordar, Reconocer (Bloom nivel 1)
Tiempo Límite	3x el tiempo base
Hints Disponibles	3 pistas
Recompensa XP	10 XP por ejercicio correcto

Ejemplos de Ejercicios:

• Emparejar imagen con palabra maya
• Seleccionar traducción correcta de saludos básicos
• Escuchar palabra y seleccionar imagen correcta
• Completar palabra faltante en oración simple

Vocabulario Típico:

• Saludos: Ba'ax ka wa'alik (¿Cómo estás?), Maalo'ob (Bien)
• Números: jump'éel (uno), ka'a (dos)
• Familia: nah (mamá), taat (papá)
• Colores básicos

---

2. Elementary (Elemental) - A2

Perfil del Estudiante:

• 2-3 meses de estudio
• Puede formar oraciones muy simples
• Edad: 7-10 años o adultos con 30+ horas de estudio

Características de Ejercicios:

Aspecto	Parámetros
Vocabulario	50-150 palabras
Gramática	Presente, pasado simple, plurales básicos
Longitud de Oraciones	5-8 palabras
Complejidad Cognitiva	Comprender (Bloom nivel 2)
Tiempo Límite	2.5x el tiempo base
Hints Disponibles	2 pistas
Recompensa XP	15 XP por ejercicio correcto

Ejemplos de Ejercicios:

• Ordenar palabras para formar oración
• Conjugar verbos simples en presente
• Responder preguntas básicas sobre texto corto
• Escribir oración usando vocabulario dado

---

3. Pre-Intermediate (Pre-Intermedio) - B1

Perfil del Estudiante:

• 4-6 meses de estudio
• Puede mantener conversaciones simples
• Edad: 9-12 años o adultos con 60+ horas

Características de Ejercicios:

Aspecto	Parámetros
Vocabulario	150-400 palabras
Gramática	Todos los tiempos básicos, condicional simple
Longitud de Oraciones	8-12 palabras
Complejidad Cognitiva	Aplicar (Bloom nivel 3)
Tiempo Límite	2x el tiempo base
Hints Disponibles	1 pista
Recompensa XP	20 XP

Ejemplos de Ejercicios:

• Completar diálogo con expresiones apropiadas
• Identificar error gramatical en oración
• Escribir párrafo corto sobre tema familiar
• Responder preguntas de comprensión sobre texto narrativo

---

4. Intermediate (Intermedio) - B2

Perfil del Estudiante:

• 7-12 meses de estudio
• Puede expresar opiniones con cierta fluidez
• Edad: 11-14 años o adultos con 100+ horas

Características de Ejercicios:

Aspecto	Parámetros
Vocabulario	400-800 palabras
Gramática	Subjuntivo, condicional compuesto
Longitud de Oraciones	12-18 palabras
Complejidad Cognitiva	Analizar (Bloom nivel 4)
Tiempo Límite	1.5x el tiempo base
Hints Disponibles	0 pistas
Recompensa XP	30 XP

Ejemplos de Ejercicios:

• Analizar diferencias sutiles entre sinónimos
• Escribir texto argumentativo breve
• Comprensión de audio con acentos regionales
• Identificar uso correcto de tiempos verbales en contexto

---

5. Upper Intermediate (Intermedio Alto) - C1

Perfil del Estudiante:

• 1-2 años de estudio
• Puede participar en discusiones complejas
• Edad: 13-16 años o adultos con 200+ horas

Características de Ejercicios:

Aspecto	Parámetros
Vocabulario	800-1500 palabras
Gramática	Estructuras avanzadas, modismos
Longitud de Oraciones	18-25 palabras
Complejidad Cognitiva	Evaluar (Bloom nivel 5)
Tiempo Límite	1.25x el tiempo base
Hints Disponibles	0 pistas
Recompensa XP	40 XP

Ejemplos de Ejercicios:

• Evaluar calidad argumentativa de texto
• Producir texto formal (carta, ensayo)
• Comprender literatura maya clásica simplificada
• Identificar registro lingüístico apropiado (formal/informal)

---

6. Advanced (Avanzado) - C2

Perfil del Estudiante:

• 2-4 años de estudio intensivo
• Dominio cercano al nativo en contextos académicos
• Edad: Adultos con 400+ horas

Características de Ejercicios:

Aspecto	Parámetros
Vocabulario	1500-3000 palabras
Gramática	Todos los aspectos gramaticales
Longitud de Oraciones	25-40 palabras
Complejidad Cognitiva	Crear (Bloom nivel 6)
Tiempo Límite	1x el tiempo base
Hints Disponibles	0 pistas
Recompensa XP	50 XP

Ejemplos de Ejercicios:

• Análisis lingüístico de texto literario
• Producción de ensayo académico
• Traducción bidireccional (maya ↔ español)
• Análisis de variantes dialectales

---

7. Proficient (Proficiente) - C2+

Perfil del Estudiante:

• 4+ años de estudio + inmersión
• Dominio nativo académico
• Maestros, lingüistas, traductores

Características de Ejercicios:

Aspecto	Parámetros
Vocabulario	3000+ palabras + arcaísmos
Gramática	Todas las estructuras + arcaísmos
Longitud de Oraciones	Ilimitada
Complejidad Cognitiva	Investigar, Innovar
Tiempo Límite	1x el tiempo base
Hints Disponibles	0 pistas
Recompensa XP	70 XP

Ejemplos de Ejercicios:

• Análisis paleográfico de textos coloniales
• Investigación etimológica
• Producción de contenido didáctico
• Análisis comparativo dialectal profundo

---

8. Native (Nativo)

Perfil del Estudiante:

• Hablante nativo del maya yucateco
• Creció hablando maya en casa/comunidad
• Objetivo: Alfabetización en lengua materna

Características de Ejercicios:

Aspecto	Parámetros
Vocabulario	Vocabulario nativo completo
Gramática	Estructuras nativas complejas
Longitud de Oraciones	Ilimitada
Complejidad Cognitiva	Meta-lingüística
Tiempo Límite	0.8x el tiempo base
Hints Disponibles	0 pistas
Recompensa XP	100 XP

Ejemplos de Ejercicios:

• Ortografía estandarizada (muchos nativos no escriben)
• Análisis de variación generacional
• Preservación y documentación de vocabulario local
• Producción de contenido para revitalización

---

🎯 Criterios de Dificultad por Aspecto

Complejidad de Vocabulario

Nivel	Palabras Conocidas	Tipo de Vocabulario
Beginner	10-50	Concreto, cotidiano
Elementary	50-150	Concreto + abstracto básico
Pre-Intermediate	150-400	Abstracto, sentimientos
Intermediate	400-800	Académico básico
Upper Intermediate	800-1500	Académico, técnico
Advanced	1500-3000	Literario, especializado
Proficient	3000+	Arcaico, variantes
Native	Nativo	Coloquialismos, regionalismos

Complejidad Gramatical

Nivel	Estructuras Gramaticales
Beginner	Presente simple, SVO básico
Elementary	Presente, pasado simple, plurales
Pre-Intermediate	Todos los tiempos básicos, condicional
Intermediate	Subjuntivo, condicional compuesto
Upper Intermediate	Voz pasiva, perífrasis verbales
Advanced	Todas las estructuras estándar
Proficient	Estructuras arcaicas, formales
Native	Idiolecto nativo completo

Longitud de Texto

Nivel	Palabras por Oración	Oraciones por Párrafo	Párrafos por Ejercicio
Beginner	3-5	1-2	1
Elementary	5-8	2-3	1-2
Pre-Intermediate	8-12	3-4	2-3
Intermediate	12-18	4-6	3-5
Upper Intermediate	18-25	6-8	5-7
Advanced	25-40	8-12	7-10
Proficient	30-50	10-15	10+
Native	Sin límite	Sin límite	Sin límite

---

💰 Recompensas por Dificultad

XP por Ejercicio

const XP_BY_DIFFICULTY = {
  beginner: 10,
  elementary: 15,
  pre_intermediate: 20,
  intermediate: 30,
  upper_intermediate: 40,
  advanced: 50,
  proficient: 70,
  native: 100
};

ML Coins por Ejercicio

const ML_COINS_BY_DIFFICULTY = {
  beginner: 2,
  elementary: 3,
  pre_intermediate: 5,
  intermediate: 7,
  upper_intermediate: 10,
  advanced: 15,
  proficient: 20,
  native: 30
};

Multiplicador por Primer Intento

Si el usuario acierta al primer intento, recibe 1.5x las recompensas:

XP de ejercicio intermediate (30) × 1.5 = 45 XP
ML Coins de intermediate (7) × 1.5 = 10 ML Coins (redondeado)

---

🔓 Desbloqueo Progresivo

Regla de Desbloqueo

Los estudiantes solo pueden acceder a ejercicios de su nivel o 1 nivel superior:

Nivel Actual del Estudiante: Intermediate (B2)
  ✅ Puede hacer: Beginner, Elementary, Pre-Intermediate, Intermediate, Upper Intermediate
  ❌ NO puede hacer: Advanced, Proficient, Native

Criterios de Promoción de Nivel

Para avanzar al siguiente nivel de dificultad, el estudiante debe:

Criterio	Requisito
Tasa de Éxito	≥80% en ejercicios del nivel actual
Ejercicios Completados	≥30 ejercicios del nivel actual
Tiempo Promedio	≤1.5x el tiempo promedio del nivel

Ejemplo:

Estudiante en nivel Pre-Intermediate:
- Tasa de éxito: 85% ✅
- Ejercicios completados: 42 ✅
- Tiempo promedio: 1.3x ✅
→ PROMOCIÓN a Intermediate

Excepciones

Maestros pueden:

• Asignar ejercicios de cualquier nivel a sus estudiantes (override automático)
• Ajustar manualmente el nivel de un estudiante

Placement Test:

• Al registrarse, estudiante hace "placement test"
• Sistema determina nivel inicial automáticamente
• Puede empezar en cualquier nivel (no necesariamente Beginner)

---

⏱️ Tiempo Límite por Dificultad

Multiplicador de Tiempo

Cada nivel tiene un multiplicador de tiempo base que se aplica según la mecánica:

Nivel	Multiplicador	Ejemplo (Base 60s)
Beginner	3.0x	180 segundos
Elementary	2.5x	150 segundos
Pre-Intermediate	2.0x	120 segundos
Intermediate	1.5x	90 segundos
Upper Intermediate	1.25x	75 segundos
Advanced	1.0x	60 segundos
Proficient	1.0x	60 segundos
Native	0.8x	48 segundos (nativos son más rápidos)

Cálculo:

const finalTimeLimit = baseTimeForMechanic * difficultyMultiplier;

// Ejemplo:
// Mecánica: Multiple Choice (base 60s)
// Dificultad: Beginner (3.0x)
// Tiempo final: 60s × 3.0 = 180s

---

💼 Casos de Uso

CU-EDU-002-01: Estudiante Realiza Placement Test

Actor: Estudiante nuevo

Precondiciones:

• Estudiante registrado
• Primer acceso al sistema

Flujo Principal:

1. Sistema detecta que es primera vez del estudiante
2. Sistema presenta "Placement Test":
   • 10 ejercicios de dificultad mixta (Beginner a Intermediate)
   • Sin tiempo límite
   • Sin penalización por fallar
3. Estudiante completa los 10 ejercicios
4. Sistema evalúa resultados:

   Resultados:
   - Beginner: 100% (3/3 correctos)
   - Elementary: 100% (3/3 correctos)
   - Pre-Intermediate: 67% (2/3 correctos)
   - Intermediate: 0% (0/1 correcto)
   

5. Sistema asigna nivel: Pre-Intermediate
6. Estudiante puede acceder a ejercicios: Beginner → Intermediate (1 nivel arriba)

Resultado:

• Nivel inicial asignado
• Estudiante puede empezar aprendizaje en nivel apropiado

---

CU-EDU-002-02: Sistema Promociona Estudiante de Nivel

Actor: Sistema (automatizado)

Trigger: Estudiante completa ejercicio

Flujo Principal:

1. Estudiante completa ejercicio de nivel Pre-Intermediate (correcto)
2. Sistema actualiza estadísticas:

   UPDATE educational_content.user_difficulty_stats
   SET
     exercises_completed = exercises_completed + 1,
     exercises_correct = exercises_correct + 1,
     success_rate = (exercises_correct::FLOAT / exercises_completed) * 100
   WHERE user_id = 'uuid' AND difficulty = 'pre_intermediate';
   

3. Sistema verifica criterios de promoción:

   Pre-Intermediate Stats:
   - Tasa de éxito: 82% ✅ (>= 80%)
   - Ejercicios completados: 35 ✅ (>= 30)
   - Tiempo promedio: 1.4x ✅ (<= 1.5x)
   

4. Criterios cumplidos → PROMOCIÓN
5. Sistema:
   • Actualiza user_profile.current_difficulty_level = 'intermediate'
   • Crea notificación: "🎉 ¡Subiste de nivel! Ahora eres Intermediate"
   • Otorga achievement: "Level Up: Intermediate"
   • Otorga bonus: 50 XP + 10 ML Coins
6. Estudiante ahora puede acceder hasta nivel Upper Intermediate

Resultado:

• Estudiante promocionado
• Acceso a ejercicios más difíciles
• Recompensa por logro

---

📊 Analytics por Nivel de Dificultad

Métricas del Sistema

Por Estudiante:

SELECT
  difficulty,
  COUNT(*) AS total_attempts,
  SUM(CASE WHEN is_correct THEN 1 ELSE 0 END) AS correct_attempts,
  ROUND(AVG(CASE WHEN is_correct THEN 100.0 ELSE 0.0 END), 2) AS success_rate,
  AVG(time_spent_seconds) AS avg_time
FROM progress_tracking.exercise_attempts ea
JOIN educational_content.exercises e ON ea.exercise_id = e.id
WHERE ea.user_id = 'uuid'
GROUP BY difficulty
ORDER BY difficulty;

Global (Admin Dashboard):

• Distribución de estudiantes por nivel
• Tasa de promoción por nivel
• Niveles más difíciles (mayor tasa de abandono)
• Tiempo promedio de permanencia en cada nivel

---

✅ Criterios de Aceptación

Para Estudiantes

• Puede realizar placement test al inicio
• Solo ve ejercicios de su nivel o 1 nivel superior
• Recibe notificación al ser promocionado de nivel
• Ve sus estadísticas por nivel en dashboard
• Entiende por qué no puede acceder a ejercicios de niveles muy altos

Para Maestros

• Puede asignar ejercicios de cualquier nivel (override)
• Puede ajustar manualmente el nivel de un estudiante
• Ve distribución de estudiantes por nivel en su clase
• Identifica estudiantes estancados en un nivel

Para Sistema

• Asigna nivel inicial basado en placement test
• Promociona automáticamente según criterios
• Calcula recompensas correctas según nivel
• Aplica tiempo límite apropiado por nivel
• Previene acceso a ejercicios fuera de rango permitido

---

🔒 Consideraciones Pedagógicas

Principio de Zona de Desarrollo Próximo (Vygotsky)

El sistema permite acceso a 1 nivel superior para mantener al estudiante en su "zona de desarrollo próximo" - desafío suficiente sin ser abrumador.

Prevención de Frustración

• Beginner → Elementary: Transición gradual, 80% de éxito requerido
• No saltos de nivel: Sistema nunca salta niveles automáticamente
• Regresión permitida: Estudiante puede hacer ejercicios de niveles más bajos para reforzar

Motivación Intrínseca

• Recompensas aumentan significativamente con nivel (10 XP → 100 XP)
• Promoción de nivel es celebrada con notificación y achievement
• Progreso visible en dashboard personal

---

📅 Historial

Versión	Fecha	Cambios
1.0	2025-11-07	Creación inicial del documento

---

Documento: docs/01-requerimientos/03-contenido-educativo/RF-EDU-002-niveles-dificultad.md Propósito: Definir 8 niveles de dificultad progresivos y sistema de promoción adaptativa