workspace/projects/gamilit/orchestration/analisis-modulos-3-4-5/FASE-3-PLAN-IMPLEMENTACIONES.md

PLAN DE IMPLEMENTACIONES Y CORRECCIONES

Módulos 3, 4 y 5 - Gamilit Platform

Fecha: 2025-12-23 Analista: Requirements-Analyst Versión: 1.0 Estado: LISTO PARA VALIDACIÓN

---

RESUMEN DEL PLAN

Hallazgos Clave del Análisis

Aspecto	Estado	Nota
Implementación de código	✅ COMPLETO	Frontend, Backend, Database
Validador M4-M5	✅ IMPLEMENTADO	Función SQL funcional
Rangos Maya	✅ CORRECTO v2.1	K'uk'ulkan desde 1,900 XP
Seeds de ejercicios	✅ COMPLETOS	M3, M4, M5 con contenido
Documentación	⚠️ DESACTUALIZADA	VISION.md dice "BACKLOG"
Rúbricas Teacher	⚠️ VERIFICAR	Posible ajuste para M4-M5

Esfuerzo Estimado

Prioridad	Correcciones	Horas Estimadas
P0 - Crítico	2	2-4 horas
P1 - Alto	3	8-12 horas
P2 - Medio	2	4-6 horas
TOTAL	7	14-22 horas

---

CORRECCIONES P0 (CRÍTICAS)

COR-001: Actualizar Documentación de Visión

Archivo: docs/00-vision-general/VISION.md

Problema: La documentación dice que M4 y M5 están en "BACKLOG - NO IMPLEMENTADOS" cuando en realidad están completamente implementados.

Corrección:

# ANTES:
## 5. SISTEMA MODULAR PROGRESIVO
| Módulo 4 | 5 | Lectura Digital y Multimodal | BACKLOG |
| Módulo 5 | 3 | Producción y Expresión Lectora | BACKLOG |

# DESPUÉS:
## 5. SISTEMA MODULAR PROGRESIVO
| Módulo 4 | 5 | Lectura Digital y Multimodal | ✅ IMPLEMENTADO |
| Módulo 5 | 3 | Producción y Expresión Lectora | ✅ IMPLEMENTADO |

Responsable: Documentation-Agent Esfuerzo: 1 hora Archivos a modificar:

• docs/00-vision-general/VISION.md
• docs/00-vision-general/RESUMEN-ACTUAL.md (si existe)

---

COR-002: Verificar Consistencia de Documentación XP

Problema: Algunas guías de prueba mencionan umbrales de XP distintos a los configurados en DB.

Verificación Requerida:

Documento	Valor	DB (v2.1)	Estado
GUIA-PRUEBAS-MODULO5	"500 XP = K'uk'ulkan"	1,900 XP	⚠️ CONFUSO
DocumentoDeDiseño v6.1	?	1,900 XP	VERIFICAR

Corrección:

• Revisar todos los documentos que mencionen umbrales de XP
• Estandarizar referencias a:
  • Ajaw: 0-499 XP
  • Nacom: 500-999 XP
  • Ah K'in: 1,000-1,499 XP
  • Halach Uinic: 1,500-1,899 XP
  • K'uk'ulkan: 1,900+ XP

Responsable: Documentation-Agent Esfuerzo: 1-2 horas

---

CORRECCIONES P1 (ALTAS)

COR-003: Configurar Rúbricas Específicas para M4-M5 en RubricEvaluator

Archivo: apps/frontend/src/apps/teacher/components/grading/RubricEvaluator.tsx

Problema: El RubricEvaluator tiene rúbricas genéricas pero puede necesitar configuraciones específicas para los 8 tipos de ejercicios de M4-M5.

Tipos que requieren rúbricas:

Módulo 4:

Tipo	Rúbrica Necesaria	Estado
verificador_fake_news	Precisión de veredictos, calidad de evidencia	VERIFICAR
infografia_interactiva	Comprensión de datos, secciones exploradas	VERIFICAR
quiz_tiktok	N/A (auto-calificable)	✅ OK
navegacion_hipertextual	Eficiencia de navegación, información sintetizada	VERIFICAR
analisis_memes	Interpretación de elementos, análisis cultural	VERIFICAR

Módulo 5:

Tipo	Rúbrica Necesaria	Estado
diario_multimedia	Precisión histórica, profundidad emocional, creatividad	VERIFICAR
comic_digital	Narrativa visual, diálogos, arco dramático	VERIFICAR
video_carta	Autenticidad de voz, mensaje, estructura	VERIFICAR

Implementación:

1. Verificar si ya existen rúbricas en RubricEvaluator.tsx
2. Si no existen, crear configuraciones basadas en las guías de pruebas
3. Cada rúbrica debe incluir:
   • Criterios con pesos (%)
   • Niveles de evaluación (0-25, 26-50, 51-75, 76-100)
   • Templates de feedback

Responsable: Frontend-Agent Esfuerzo: 4-6 horas

---

COR-004: Verificar Integración de Quiz TikTok con Gamificación

Problema: Quiz TikTok (4.3) es el único ejercicio auto-calificable de M4. Verificar que:

1. El scoring automático calcula correctamente (0/33/67/100)
2. XP y ML Coins se otorgan en primer acierto
3. El resultado se refleja en portal de teacher

Archivos a verificar:

• apps/backend/src/modules/educational/services/exercises.service.ts
• apps/frontend/src/features/mechanics/module4/QuizTikTok/QuizTikTokExercise.tsx

Tests requeridos:

// Test Case 1: 3/3 correctas → 100 puntos, XP otorgado
// Test Case 2: 2/3 correctas → 67 puntos, XP proporcional
// Test Case 3: 0/3 correctas → 0 puntos, sin XP
// Test Case 4: Segundo intento correcto → sin XP (anti-farming)

Responsable: Backend-Agent / QA-Agent Esfuerzo: 2-3 horas

---

COR-005: Implementar Pruebas E2E para Flujo Completo

Flujo a probar:

1. Estudiante abre ejercicio M4/M5
2. Completa ejercicio
3. Envía respuesta
4. Sistema valida estructura (validate_module4_module5_answer)
5. Sistema crea ExerciseAttempt/ExerciseSubmission
6. Triggers actualizan XP, ML Coins, misiones
7. Docente ve respuesta en ReviewPanel
8. Docente califica con rúbrica
9. Sistema otorga puntuación final
10. Estudiante ve feedback

Casos de prueba:

ID	Escenario	Ejercicio	Resultado Esperado
E2E-M4-01	Verificador FakeNews - Respuesta válida	4.1	Guardado, pendiente revisión
E2E-M4-02	Quiz TikTok - 3/3 correctas	4.3	100 pts, XP otorgado inmediato
E2E-M4-03	Análisis Memes - Estructura inválida	4.5	Error de validación
E2E-M5-01	Diario Multimedia - 3 entradas	5.1	Guardado, 500 XP pendiente
E2E-M5-02	Video Carta - Solo script	5.3	Guardado, pendiente revisión
E2E-M5-03	Docente califica M5	5.1	XP y ML Coins otorgados

Responsable: QA-Agent Esfuerzo: 4-6 horas

---

CORRECCIONES P2 (MEDIAS)

COR-006: Verificar Multiplicador ML Coins por Rango

Problema: El análisis indica que el multiplicador de ML Coins por rango podría no estar implementado. Actualmente solo XP tiene multiplicador.

Verificar en:

• apps/database/ddl/schemas/gamification_system/functions/award_ml_coins.sql
• apps/backend/src/modules/gamification/services/ml-coins.service.ts

Comportamiento esperado:

-- Si usuario tiene rango Nacom (1.10x multiplicador):
-- ML Coins base: 50
-- ML Coins finales: 50 * 1.10 = 55

Si no implementado, agregar:

-- En award_ml_coins:
SELECT xp_multiplier INTO v_multiplier
FROM gamification_system.maya_ranks
WHERE rank_name = (
  SELECT current_rank FROM gamification_system.user_stats WHERE user_id = p_user_id
);

v_final_amount := FLOOR(p_amount * v_multiplier);

Responsable: Database-Agent Esfuerzo: 2-3 horas

---

COR-007: Configurar Storage para Video Upload (M5)

Problema: Video-Carta (5.3) permite subir videos pero requiere configuración de storage.

Opciones:

1. Local Storage (desarrollo): /uploads/videos/
2. S3/MinIO (producción): Bucket dedicado
3. Supabase Storage (si aplica)

Configuración requerida:

// En backend:
upload: {
  maxFileSize: 100 * 1024 * 1024, // 100MB
  allowedMimeTypes: ['video/mp4', 'video/webm', 'video/mov'],
  destination: process.env.VIDEO_UPLOAD_PATH || './uploads/videos'
}

Responsable: Infra-Agent / Backend-Agent Esfuerzo: 2-3 horas

---

MATRIZ DE DEPENDENCIAS

┌─────────────────────────────────────────────────────────────────┐
│ COR-001 (Docs VISION)                                           │
│    ↓                                                            │
│ COR-002 (Docs XP) ──────────────────────────────────────────→   │
│    ↓                                                            │
│ COR-003 (Rúbricas) ← PUEDE PARALELO CON COR-004/005             │
│                                                                 │
│ COR-004 (Quiz TikTok) ─────→ COR-005 (E2E Tests)               │
│                                                                 │
│ COR-006 (ML Coins Mult) ← INDEPENDIENTE                         │
│                                                                 │
│ COR-007 (Video Storage) ← INDEPENDIENTE                         │
└─────────────────────────────────────────────────────────────────┘

---

ORDEN DE EJECUCIÓN RECOMENDADO

Sprint 1 (Inmediato)

Orden	ID	Descripción	Paralelo
1	COR-001	Actualizar VISION.md	NO
2	COR-002	Verificar docs XP	NO
3a	COR-003	Rúbricas M4-M5	SÍ con 3b
3b	COR-004	Quiz TikTok	SÍ con 3a

Sprint 2

Orden	ID	Descripción	Paralelo
4	COR-005	Tests E2E	NO (depende de 3a, 3b)
5a	COR-006	ML Coins Mult	SÍ con 5b
5b	COR-007	Video Storage	SÍ con 5a

---

ARCHIVOS AFECTADOS (RESUMEN)

Documentación

• docs/00-vision-general/VISION.md
• docs/00-vision-general/DocumentoDeDiseño_Mecanicas_GAMILIT_v6_1.md (verificar)

Frontend

• apps/frontend/src/apps/teacher/components/grading/RubricEvaluator.tsx
• apps/frontend/src/features/mechanics/module4/QuizTikTok/QuizTikTokExercise.tsx

Backend

• apps/backend/src/modules/gamification/services/ml-coins.service.ts
• apps/backend/src/modules/educational/services/exercises.service.ts

Database

• apps/database/ddl/schemas/gamification_system/functions/award_ml_coins.sql

Infraestructura

• .env (VIDEO_UPLOAD_PATH)
• Configuración de S3/MinIO (si aplica)

---

CRITERIOS DE ACEPTACIÓN

Para cada corrección:

ID	Criterio	Verificación
COR-001	VISION.md actualizado con estado correcto	Revisión manual
COR-002	Todos los docs usan mismos umbrales XP	Grep "K'uk'ulkan" en docs
COR-003	Rúbricas configuradas para 7 tipos M4-M5	Review de código
COR-004	Quiz TikTok otorga XP correctamente	Test automatizado
COR-005	Tests E2E pasando para 6 escenarios	CI/CD verde
COR-006	ML Coins con multiplicador por rango	Test SQL
COR-007	Videos se pueden subir y almacenar	Test manual

---

RIESGOS IDENTIFICADOS

Riesgo	Probabilidad	Impacto	Mitigación
Rúbricas inconsistentes con guías de prueba	Media	Alto	Validar contra GUIA-PRUEBAS antes de implementar
Quiz TikTok con cálculo incorrecto	Baja	Alto	Tests unitarios extensivos
Storage no configurado en producción	Media	Medio	Documentar requisitos en README
Conflictos de merge por cambios en docs	Baja	Bajo	Comunicar cambios al equipo

---

NOTAS FINALES

1. Priorizar COR-001 y COR-002 ya que la documentación incorrecta puede causar confusión en todo el equipo.

2. COR-003 (Rúbricas) es crítico para que los docentes puedan evaluar consistentemente los ejercicios de M4-M5.

3. COR-005 (E2E) debe ejecutarse DESPUÉS de las correcciones previas para validar el flujo completo.

4. COR-006 y COR-007 son mejoras opcionales que pueden implementarse en un sprint posterior si el tiempo es limitado.

---

Documento generado: 2025-12-23 Estado: FASE 3 COMPLETA - Listo para Fase 4 (Validación)