workspace/projects/gamilit/orchestration/analisis/ANALISIS-CORRECCIONES-M4-M5-2025-12-18.md

ANALISIS DE CORRECCIONES: MODULOS 4 Y 5 - PORTAL ESTUDIANTE

Fecha: 2025-12-18 Rol: Requirements Analyst Proyecto: Gamilit Versión: 1.0.0

---

1. RESUMEN EJECUTIVO

1.1 Contexto

Los módulos 4 (Lectura Digital y Multimodal) y 5 (Producción y Expresión Lectora) del portal de estudiantes presentan inconsistencias en estilos, UX/UI, funcionalidad y estructura respecto a los módulos 2 y 3 que sirven como referencia.

1.2 Hallazgos Principales

Capa	M2/M3 (Referencia)	M4	M5
Frontend	100% completo	62% completo	0% estructura
Backend DTOs	100%	55% (5/9)	100% (4/4)
Database Seeds	100%	100%	100%
Documentación	100%	30%	0%

1.3 Gaps Críticos Identificados

1. M5 Frontend CRÍTICO: Cero archivos de tipos, mock data, schemas
2. M4 Backend: 4 DTOs faltantes (ResanaCritica, ChatLiterario, EmailFormal, EnsayoArgumentativo)
3. M4 Frontend: 4 ejercicios sin estructura de soporte completa
4. UX/UI: Inconsistencias visuales y de distribución de componentes
5. Gamificación: Validar integración con sistema de XP/ML Coins

---

2. INVENTARIO DE COMPONENTES

2.1 Módulo 4: Lectura Digital y Multimodal

Ejercicios Definidos (9)

ID	Ejercicio	Frontend	Backend DTO	DB Seed	Estado
4.1	Verificador Fake News	✅	✅	✅	Completo
4.2	Infografía Interactiva	✅	✅	✅	Completo
4.3	Quiz TikTok	✅	✅	✅	Completo
4.4	Navegación Hipertextual	✅	✅	✅	Completo
4.5	Análisis de Memes	✅	✅	✅	Completo
4.6	Reseña Crítica	⚠️ Parcial	❌ FALTA	❌	Incompleto
4.7	Chat Literario	⚠️ Parcial	❌ FALTA	❌	Incompleto
4.8	Email Formal	⚠️ Parcial	❌ FALTA	❌	Incompleto
4.9	Ensayo Argumentativo	⚠️ Parcial	❌ FALTA	❌	Incompleto

Estructura de Archivos Frontend M4

features/mechanics/module4/
├── AnalisisMemes/
│   ├── AnalisisMemesExercise.tsx      ✅ (453 LOC)
│   ├── analisisMemesTypes.ts          ✅
│   ├── analisisMemesSchemas.ts        ✅
│   ├── analisisMemeMockData.ts        ✅
│   ├── MemeAnnotator.tsx              ✅
│   └── AnnotationMarker.tsx           ✅
├── ChatLiterario/
│   ├── ChatLiterarioExercise.tsx      ⚠️ (393 LOC)
│   ├── chatLiterarioTypes.ts          ✅ (pero incompleto)
│   ├── chatLiterarioMockData.ts       ❌ FALTA
│   └── chatLiterarioSchemas.ts        ❌ FALTA
├── EmailFormal/
│   ├── EmailFormalExercise.tsx        ⚠️ (431 LOC)
│   ├── emailFormalTypes.ts            ✅ (pero incompleto)
│   ├── emailFormalMockData.ts         ❌ FALTA
│   └── emailFormalSchemas.ts          ❌ FALTA
├── EnsayoArgumentativo/
│   ├── EnsayoArgumentativoExercise.tsx ⚠️ (572 LOC)
│   ├── ensayoArgumentativoTypes.ts    ❌ FALTA
│   ├── ensayoArgumentativoMockData.ts ❌ FALTA
│   └── ensayoArgumentativoSchemas.ts  ❌ FALTA
├── InfografiaInteractiva/
│   ├── InfografiaInteractivaExercise.tsx ✅ (607 LOC)
│   ├── infografiaInteractivaTypes.ts  ✅
│   ├── infografiaInteractivaSchemas.ts ✅
│   ├── infografiaInteractivaMockData.ts ✅
│   ├── DraggableCard.tsx              ✅
│   ├── DroppableZone.tsx              ✅
│   └── DataVisualization.tsx          ✅
├── NavegacionHipertextual/
│   ├── NavegacionHipertextualExercise.tsx ✅ (280 LOC)
│   ├── navegacionHipertextualTypes.ts ✅
│   ├── navegacionHipertextualSchemas.ts ✅
│   ├── navegacionHipertextualMockData.ts ✅
│   ├── HypertextDocument.tsx          ✅
│   └── Breadcrumbs.tsx                ✅
├── QuizTikTok/
│   ├── QuizTikTokExercise.tsx         ✅ (691 LOC)
│   ├── quizTikTokTypes.ts             ✅
│   ├── quizTikTokSchemas.ts           ✅
│   ├── quizTikTokMockData.ts          ✅
│   ├── TikTokCard.tsx                 ✅
│   └── SwipeGesture.tsx               ⚠️ PLACEHOLDER VACIO
├── ResenaCritica/
│   ├── ResenaCriticaExercise.tsx      ⚠️ (456 LOC)
│   ├── resenaCriticaTypes.ts          ✅ (pero incompleto)
│   ├── resenaCriticaMockData.ts       ❌ FALTA
│   └── resenaCriticaSchemas.ts        ❌ FALTA
└── VerificadorFakeNews/
    ├── VerificadorFakeNewsExercise.tsx ✅ (374 LOC)
    ├── verificadorFakeNewsTypes.ts    ✅
    ├── verificadorFakeNewsSchemas.ts  ✅
    ├── verificadorFakeNewsMockData.ts ✅
    ├── ArticleParser.tsx              ✅
    └── FactCheckDashboard.tsx         ✅

2.2 Módulo 5: Producción y Expresión Lectora

Ejercicios Definidos (3 opciones, elegir 1)

ID	Ejercicio	Frontend	Backend DTO	DB Seed	Estado
5A	Diario Multimedia	⚠️ Monolítico	✅	✅	Incompleto
5B	Cómic Digital	⚠️ Monolítico	✅	✅	Incompleto
5C	Video Carta	⚠️ Monolítico	✅	✅	Incompleto

Estructura de Archivos Frontend M5 (CRÍTICA)

features/mechanics/module5/
├── ComicDigital/
│   └── ComicDigitalExercise.tsx       ⚠️ (369 LOC - TODO INLINE)
│   ├── comicDigitalTypes.ts           ❌ FALTA
│   ├── comicDigitalMockData.ts        ❌ FALTA
│   └── comicDigitalSchemas.ts         ❌ FALTA
├── DiarioMultimedia/
│   └── DiarioMultimediaExercise.tsx   ⚠️ (443 LOC - TODO INLINE)
│   ├── diarioMultimediaTypes.ts       ❌ FALTA
│   ├── diarioMultimediaMockData.ts    ❌ FALTA
│   └── diarioMultimediaSchemas.ts     ❌ FALTA
└── VideoCarta/
    └── VideoCartaExercise.tsx         ⚠️ (576 LOC - TODO INLINE)
    ├── videoCartaTypes.ts             ❌ FALTA
    ├── videoCartaMockData.ts          ❌ FALTA
    └── videoCartaSchemas.ts           ❌ FALTA

PROBLEMA CRÍTICO M5: Todos los tipos están inline en los .tsx, sin archivos de soporte.

---

3. ANÁLISIS DE GAPS POR CAPA

3.1 Frontend - Gaps de Estructura

M4: Archivos Faltantes (16 archivos)

Ejercicio	Types	MockData	Schemas	Componentes
ChatLiterario	⚠️ Parcial	❌	❌	❌ MessageBubble
EmailFormal	⚠️ Parcial	❌	❌	-
EnsayoArgumentativo	❌	❌	❌	-
ResenaCritica	⚠️ Parcial	❌	❌	-
QuizTikTok	✅	✅	✅	⚠️ SwipeGesture vacío

M5: Archivos Faltantes (9 archivos críticos)

Ejercicio	Types	MockData	Schemas	Componentes
ComicDigital	❌	❌	❌	❌ ComicPanel, SpeechBubble
DiarioMultimedia	❌	❌	❌	❌ DiaryEntry, MoodSelector
VideoCarta	❌	❌	❌	- (usa useSectionedRecorder)

3.2 Backend - Gaps de DTOs

DTOs Faltantes en M4 (4)

// FALTA CREAR:
1. ResenaCriticaAnswerDto
   - Estructura: { title, content, rating, aspects[] }
   - Validación: min 150 palabras, rating 1-5

2. ChatLiterarioAnswerDto
   - Estructura: { messages[], characterId, totalTurns }
   - Validación: min 5 turnos, mensajes no vacíos

3. EmailFormalAnswerDto
   - Estructura: { subject, recipient, body, greeting, farewell }
   - Validación: formato email, min 100 palabras body

4. EnsayoArgumentativoAnswerDto
   - Estructura: { introduction, arguments[], conclusion }
   - Validación: min 3 argumentos, 200+ palabras total

Validador Centralizado - Casos Faltantes

Archivo: progress/dto/answers/exercise-answer.validator.ts

// FALTA AGREGAR CASE para:
case 'resena_critica':
case 'chat_literario':
case 'email_formal':
case 'ensayo_argumentativo':

3.3 Database - Estado

Componente	M4	M5	Notas
exercise_type ENUM	✅ 5 tipos	✅ 3 tipos	Completo
Seeds DEV	✅ 5 ejercicios	✅ 3 ejercicios	OK
Seeds PROD	✅ 9 ejercicios	✅ 3 ejercicios	OK
Validadores SQL	⚠️ Solo estructura	⚠️ Solo estructura	requires_manual_review=TRUE
exercise_validation_config	❌ No tiene entrada	❌ No tiene entrada	Por diseño (manual)

---

4. ANÁLISIS UX/UI

4.1 Patrones de Referencia (M2/M3)

Patrón	Descripción	Implementado M2/M3
FeedbackModal	Modal de retroalimentación post-submit	✅
ProgressTracker	Barra de progreso visual	✅
TimerWidget	Temporizador con colores de alerta	✅
ScoreDisplay	Mostrador de puntuación en tiempo real	✅
DetectiveCard	Tarjeta estilizada para contenido	✅
LoadingStates	Spinners y skeletons	✅
ErrorHandling	Toasts y modales de error	✅

4.2 Inconsistencias Detectadas en M4/M5

Distribución de Componentes

• M2/M3: Estructura consistente con header, content, footer
• M4: Variada - algunos ejercicios no siguen el patrón
• M5: Monolítica - todo mezclado en un solo componente

Estilos y Temas

• M2/M3: Uso de Tailwind classes consistentes, tema "detective"
• M4: Mezcla de estilos, algunos sin tema coherente
• M5: Estilos inline en algunos casos

UX Issues Potenciales

1. QuizTikTok: SwipeGesture es placeholder vacío (no hay swipe real)
2. InfografiaInteractiva: Drag-and-drop puede no ser accesible
3. VideoCarta: Validar grabación sectionalizada en móviles
4. ComicDigital: Editor de cómic básico, sin plantillas

4.3 Validación con Documento de Diseño

Documento: docs/00-vision-general/DocumentoDeDiseño_Mecanicas_GAMILIT_v6_1.md

Especificación	M4	M5	Estado
Verificador Fake News: 3 claims, evidencia min 10 chars	✅	-	OK
Infografía: 3 secciones, 2 preguntas	✅	-	OK
Quiz TikTok: 10 preguntas, 6 seg c/u	⚠️ 3 preg	-	Revisar seeds
Navegación Hipertextual: 5 tesoros	⚠️	-	Revisar implementación
Análisis Memes: 1 meme, 4 elementos	✅	-	OK
Diario: 5 entradas, 150 palabras c/u	-	✅	OK
Cómic: 4-6 viñetas	-	✅	OK
Video-Carta: 2-3 min o 400-600 palabras	-	✅	OK

---

5. PLAN DE ANÁLISIS DETALLADO

5.1 Fase 1: Análisis de Coherencia (Actual)

Estado: COMPLETADO Entregables:

• Inventario de componentes M4/M5
• Identificación de gaps Frontend
• Identificación de gaps Backend
• Estado de Database
• Matriz de completitud

5.2 Fase 2: Ejecución de Análisis Profundo

Subagentes Requeridos:

2.1 Frontend-Auditor (M4)

Tarea: Auditar ejercicios M4 incompletos
Alcance:
  - ChatLiterario: Revisar estructura, identificar tipos faltantes
  - EmailFormal: Revisar estructura, identificar tipos faltantes
  - EnsayoArgumentativo: Revisar estructura, identificar tipos faltantes
  - ResenaCritica: Revisar estructura, identificar tipos faltantes
  - QuizTikTok: Implementar SwipeGesture real
Entregables:
  - Lista de tipos a extraer por ejercicio
  - Especificación de schemas Zod requeridos
  - Mock data necesario

2.2 Frontend-Auditor (M5)

Tarea: Auditar ejercicios M5 (refactor completo)
Alcance:
  - Extraer interfaces de cada .tsx a *Types.ts
  - Definir schemas Zod para validación
  - Crear mock data para desarrollo
  - Identificar componentes reutilizables a extraer
Entregables:
  - Especificación de refactor por ejercicio
  - Lista de componentes auxiliares a crear

2.3 Backend-Auditor (M4)

Tarea: Auditar DTOs faltantes M4
Alcance:
  - Definir estructura de DTOs faltantes
  - Validadores class-validator necesarios
  - Casos a agregar en ExerciseAnswerValidator
Entregables:
  - Especificación de DTOs a crear
  - Validadores requeridos

2.4 UX-Auditor

Tarea: Auditar UX/UI M4/M5 vs M2/M3
Alcance:
  - Comparar distribución de componentes
  - Identificar inconsistencias de estilos
  - Validar accesibilidad
  - Revisar responsive design
Entregables:
  - Lista de correcciones UX/UI
  - Guía de estilos a seguir

5.3 Fase 3: Planeación de Implementaciones

Entregables esperados:

1. Lista priorizada de tareas de corrección
2. Dependencias entre tareas
3. Estimación de esfuerzo (story points)
4. Asignación a agentes especialistas

5.4 Fase 4: Validación de Planeación

Checklist de validación:

• Todos los componentes dependientes identificados
• Impacto en otros portales (admin, teacher) evaluado
• Integración con gamificación validada
• Seeds de BD alineados con implementación
• Documentación actualizada

5.5 Fase 5: Ejecución de Correcciones

Orden de implementación propuesto:

1. M5 Frontend (crítico - refactor estructura)
2. M4 Backend DTOs (bloqueante para submit)
3. M4 Frontend archivos faltantes
4. UX/UI correcciones transversales
5. Tests y validación

---

6. MATRIZ DE DEPENDENCIAS

6.1 Dependencias Internas

M5 Frontend Refactor
    └── Requiere: Definición de tipos/schemas
    └── Bloquea: Testing E2E de M5

M4 Backend DTOs
    └── Requiere: Especificación de estructura
    └── Bloquea: Submit de ejercicios M4 incompletos

M4 Frontend MockData
    └── Requiere: Tipos definidos
    └── Bloquea: Desarrollo local sin BD

UX/UI Correcciones
    └── Requiere: Componentes base estables
    └── Bloquea: Release a producción

6.2 Dependencias Externas

Componente M4/M5	Depende de	Es dependencia de
Submit Ejercicio	Backend DTO, Validator	Gamificación (XP/ML)
FeedbackModal	-	Todos los ejercicios
useExerciseSubmission	Backend endpoint	Todos los ejercicios
Progress Tracker	exercise_attempts/submissions	Dashboard estudiante

6.3 Integraciones con Gamificación

Sistema	Afecta M4/M5	Validar
XP Rewards	Sí - 100 XP por ejercicio M4, 500 XP M5	Cálculo correcto
ML Coins	Sí - 20 ML base	Cálculo correcto
Rangos Maya	Sí - progresión a HALACH UINIC/K'UK'ULKAN	Umbrales correctos
Achievements	Potencialmente	Logros por completar módulos
Leaderboard	Sí	Actualización en tiempo real

---

7. RIESGOS IDENTIFICADOS

Riesgo	Probabilidad	Impacto	Mitigación
M5 refactor rompe funcionalidad	Media	Alto	Tests antes de refactor
DTOs M4 faltantes bloquean producción	Alta	Alto	Priorizar implementación
Inconsistencias UX afectan usabilidad	Media	Medio	Guía de estilos
Seeds no alineados con implementación	Baja	Medio	Validación cruzada
Integración gamificación incorrecta	Media	Alto	Tests E2E

---

8. PRÓXIMOS PASOS

Inmediato (Fase 2)

1. Lanzar subagente Frontend-Auditor M5
2. Lanzar subagente Backend-Auditor M4
3. Consolidar hallazgos

Corto Plazo (Fase 3)

1. Crear plan de implementación priorizado
2. Definir tareas con dependencias
3. Estimar esfuerzo

Mediano Plazo (Fase 4-5)

1. Validar plan contra análisis
2. Ejecutar correcciones
3. Validar integración completa

---

9. REFERENCIAS

Documentación

• docs/00-vision-general/DocumentoDeDiseño_Mecanicas_GAMILIT_v6_1.md
• docs/90-transversal/features/FEATURES-IMPLEMENTADAS.md

Código Referencia (M2/M3)

• features/mechanics/module2/DetectiveTextual/ - Patrón a seguir
• features/mechanics/module3/MatrizPerspectivas/ - Integración IA

Inventarios

• orchestration/inventarios/FRONTEND_INVENTORY.yml
• orchestration/inventarios/BACKEND_INVENTORY.yml
• orchestration/inventarios/DATABASE_INVENTORY.yml

---

Generado por: Requirements Analyst Fecha: 2025-12-18 Versión: 1.0.0