workspace-v1/projects/gamilit/orchestration/agentes/requirements-analyst/ANALISIS-GAPS-REALES-VALIDACION-2025-12-05.md

ANÁLISIS DE GAPS REALES - Validación Exhaustiva

Proyecto: GAMILIT - Sistema de Gamificación Educativa Fecha: 2025-12-05 Autor: Requirements-Analyst Versión: 1.0

---

RESUMEN EJECUTIVO

Este documento consolida los hallazgos de una validación exhaustiva del código real del proyecto GAMILIT, identificando gaps entre la documentación/diseño y la implementación real.

Área	Estado Documentado	Estado Real	Gap
Teacher Portal	82% (14/17 páginas)	41% funcional	41%
Admin Portal	80% (12/15 páginas)	73% funcional	7%
Sistema Misiones	100% Done	35% funcional	65%
Módulos M4-M5	70% infraestructura	45% funcional	25%
Coherencia DTOs	No evaluado	38 inconsistencias	CRÍTICO
Notificaciones	100% Done	85% funcional	15%
Settings/Preferencias	No documentado	60% funcional	40%

Completitud Real del Proyecto: ~55% (vs 75% documentado)

---

1. SISTEMA DE MISIONES - CRÍTICO

1.1 CRON Jobs Completamente Deshabilitados

Archivo: apps/backend/src/modules/gamification/services/missions-cron.service.ts

// LÍNEAS 45-67 - TODOS LOS CRON ESTÁN COMENTADOS
// @Cron('0 0 * * *') // Deshabilitado
// @Cron('0 0 * * 0') // Deshabilitado
// @Cron('*/5 * * * *') // Deshabilitado

Impacto:

• Misiones diarias NO se resetean automáticamente a medianoche
• Misiones semanales NO se generan los domingos
• El progreso de misiones NO se actualiza periódicamente
• Los estudiantes ven misiones antiguas o vacías

1.2 Estadísticas de Racha No Implementadas

Archivo: apps/backend/src/modules/gamification/services/missions.service.ts Línea: 693

// TODO: Implementar cálculo real de racha
return {
  currentStreak: 0, // Siempre retorna 0
  longestStreak: 0, // Siempre retorna 0
  totalDaysActive: 0,
};

Impacto:

• El badge de racha muestra siempre "0 días"
• No hay motivación por mantener rachas
• Feature prometida en diseño no funciona

1.3 Misiones Hardcodeadas

Archivo: apps/backend/src/modules/gamification/services/missions.service.ts Líneas: 234-298

Las misiones se generan con templates hardcodeados en código:

const dailyTemplates = [
  { type: 'complete_exercise', target: 3, xp: 50, mlCoins: 10 },
  { type: 'study_time', target: 30, xp: 40, mlCoins: 8 },
  // ... más templates fijos
];

Problema: No hay tabla mission_templates ni administración de misiones desde Admin Portal.

1.4 Tareas Pendientes

Tarea	Prioridad	SP	Descripción
MISSION-001	P0	3	Habilitar y probar CRON jobs
MISSION-002	P0	5	Implementar cálculo real de rachas
MISSION-003	P1	8	Crear tabla mission_templates
MISSION-004	P1	5	CRUD de templates en Admin
MISSION-005	P2	3	Logs y monitoreo de misiones

---

2. TEACHER PORTAL - 10 PÁGINAS CON PROBLEMAS

2.1 Fallback a Mock User ID

Patrón repetido en 10 páginas:

const userId = user?.id || 'mock-teacher-id';

Archivos afectados:

1. TeacherDashboardPage.tsx - Línea 45
2. TeacherStudentsPage.tsx - Línea 38
3. TeacherProgressPage.tsx - Línea 52
4. TeacherActivitiesPage.tsx - Línea 41
5. TeacherGamificationPage.tsx - Línea 47
6. TeacherNotificationsPage.tsx - Línea 35
7. TeacherCalendarPage.tsx - Línea 43
8. TeacherAnalyticsPage.tsx - Línea 56
9. TeacherMissionsPage.tsx - Línea 39
10. TeacherClassroomsPage.tsx - Línea 44

Impacto: Si el auth falla silenciosamente, las páginas cargan datos de un usuario mock inexistente.

2.2 Nombre de Organización Hardcodeado

Archivo: apps/frontend/src/features/teacher/pages/TeacherDashboardPage.tsx Línea: 89

organizationName="Escuela Primaria Miguel Hidalgo"

Debería: Obtener de user.organization.name o del tenant actual.

2.3 Promedio de Progreso Siempre 0

Archivo: apps/frontend/src/features/teacher/pages/TeacherProgressPage.tsx Línea: 67

// TODO: Calcular promedio real
averageScore: 0,

2.4 Páginas Completamente Deshabilitadas

Archivo: apps/frontend/src/features/teacher/constants/featureFlags.ts

export const TEACHER_FEATURES = {
  SHOW_COMMUNICATION: false,  // Under Construction
  SHOW_CONTENT: false,        // Under Construction
  SHOW_RESOURCES: false,      // Under Construction
};

Páginas afectadas:

• TeacherCommunicationPage.tsx - Muestra "Próximamente"
• TeacherContentPage.tsx - Muestra "En Desarrollo"
• TeacherResourcesPage.tsx - Muestra "Próximamente"

2.5 Tareas Pendientes

Tarea	Prioridad	SP	Descripción
TEACHER-001	P0	3	Eliminar fallback a mock-teacher-id
TEACHER-002	P0	2	Obtener organizationName dinámicamente
TEACHER-003	P1	3	Implementar cálculo de averageScore
TEACHER-004	P1	8	Implementar TeacherCommunicationPage
TEACHER-005	P2	8	Implementar TeacherContentPage
TEACHER-006	P2	5	Implementar TeacherResourcesPage

---

3. ADMIN PORTAL - ISSUES IDENTIFICADOS

3.1 Classrooms Hardcodeados

Archivo: apps/frontend/src/features/admin/pages/AdminProgressPage.tsx Líneas: 40-44

const MOCK_CLASSROOMS = [
  { id: '1', name: 'Grupo 4A', grade: '4to' },
  { id: '2', name: 'Grupo 4B', grade: '4to' },
  { id: '3', name: 'Grupo 5A', grade: '5to' },
];

Debería: Llamar a GET /api/v1/admin/classrooms para obtener aulas reales.

3.2 Página Advanced Deshabilitada

Archivo: apps/frontend/src/features/admin/pages/AdminAdvancedPage.tsx Línea: 23

const SHOW_CONTENT = false; // Coming Soon

Contenido: Feature flags, configuración avanzada, mantenimiento del sistema.

3.3 Reports en Memoria

Archivo: apps/frontend/src/features/admin/pages/AdminReportsPage.tsx Línea: 156

// BETA: Reports stored in memory, not persistent
const [savedReports, setSavedReports] = useState<Report[]>([]);

Problema: Los reportes guardados se pierden al recargar la página.

3.4 Tareas Pendientes

Tarea	Prioridad	SP	Descripción
ADMIN-001	P0	2	Reemplazar MOCK_CLASSROOMS con API
ADMIN-002	P1	8	Implementar AdminAdvancedPage
ADMIN-003	P1	5	Persistir reports en backend
ADMIN-004	P2	3	Implementar feature flags backend

---

4. MÓDULOS M4-M5 - FEATURES FALTANTES

4.1 Verificador Fake News (M4)

Diseño vs Implementación:

Feature	Diseño	Implementado
Interfaz swipe estilo Tinder	Sí	Sí
Fact-checking real (API externa)	Sí	NO
Detección de imágenes manipuladas	Sí	NO
Validación de evidencia (min 10 chars)	Sí	Solo frontend

Archivo: apps/frontend/src/features/mechanics/module4/VerificadorFakeNews.tsx

// Línea 234 - TODO: Integrar API de fact-checking
const verifyWithAPI = async (claim: string) => {
  // Simulado - retorna resultado aleatorio
  return Math.random() > 0.5;
};

4.2 Infografía Interactiva (M4)

Feature	Diseño	Implementado
Drag & drop elementos	Sí	NO
Click para revelar	Alternativo	Sí
Zoom en secciones	Sí	Parcial
Exportar como imagen	Sí	NO

4.3 Quiz TikTok (M4)

Feature	Diseño	Implementado
Timer visual	Sí	Sí
Penalización por tiempo	Sí	NO
Animaciones transición	Sí	Parcial
Sonidos feedback	Sí	NO

Archivo: apps/frontend/src/features/mechanics/module4/QuizTikTok.tsx Línea: 145

// TODO: Implementar penalización por tiempo
// El timer es solo visual, no afecta puntuación

4.4 Diario Reflexivo (M5)

Feature	Diseño	Implementado
Mínimo 150 palabras	Sí	NO
Prompts guiados	Sí	Sí
Guardado automático	Sí	Sí
Análisis de sentimiento	Sí	NO

4.5 Video Carta a Curie (M5)

Feature	Diseño	Implementado
Grabación video	Sí	Sí
4 secciones cronometradas	Sí	NO
Preview antes de enviar	Sí	Sí
Compresión automática	Sí	Parcial

4.6 Podcast Curie (M5)

Feature	Diseño	Implementado
Grabación audio	Sí	Sí
Edición básica	Sí	NO
Transcripción automática	Sí	NO
Inserción de música/efectos	Sí	NO

4.7 DTOs Backend Faltantes

Archivo esperado: apps/backend/src/modules/educational/dto/module4/

Los DTOs documentados en US-M4-001 NO EXISTEN:

• verificador-fake-news-answer.dto.ts - NO EXISTE
• infografia-interactiva-answer.dto.ts - NO EXISTE
• quiz-tiktok-answer.dto.ts - NO EXISTE
• navegacion-hipertextual-answer.dto.ts - NO EXISTE
• analisis-memes-answer.dto.ts - NO EXISTE

Validación actual: Se usa un DTO genérico ExerciseSubmissionDto sin validación específica.

4.8 Tareas Pendientes

Tarea	Prioridad	SP	Descripción
M4-001	P0	5	Crear 5 DTOs específicos M4
M4-002	P1	8	Integrar API fact-checking
M4-003	P1	5	Implementar drag-drop infografía
M4-004	P2	3	Penalización tiempo Quiz
M5-001	P0	5	Crear 3 DTOs específicos M5
M5-002	P1	3	Validación 150 palabras diario
M5-003	P1	5	Secciones cronometradas video
M5-004	P2	8	Edición básica podcast

---

5. COHERENCIA DTOs - 38 INCONSISTENCIAS

5.1 Inconsistencias Críticas (5)

5.1.1 UserStats - Tipo No Definido en Frontend

Backend: apps/backend/src/modules/gamification/dto/user-stats.dto.ts

export class UserStatsDto {
  totalXp: number;
  totalMlCoins: number;
  currentRank: string;
  // ...
}

Frontend: No existe types/userStats.ts - Se usa any en múltiples lugares.

5.1.2 Classroom - Tipo Incompleto

Database: 15 columnas en tenants.classrooms Backend: 12 campos en ClassroomDto Frontend: 8 campos en tipo local

Campos perdidos: max_students, is_active, metadata, created_by, academic_year

5.1.3 User - Campos Inconsistentes

Campo	Database	Backend	Frontend
created_at	TIMESTAMP	Date	string
last_login	TIMESTAMP	Date	NO EXISTE
metadata	JSONB	object	NO EXISTE
is_verified	BOOLEAN	boolean	NO EXISTE

5.1.4 ExerciseSubmission - JSONB Sin Tipado

Database: content JSONB sin restricciones Backend: content: Record<string, any> Frontend: content: unknown

Problema: No hay validación de estructura del contenido por tipo de ejercicio.

5.1.5 INTERVAL No Convertido

Database: study_time INTERVAL Backend: Retorna string "01:30:00" Frontend: Espera number (minutos)

5.2 Inconsistencias Medias (15)

Área	Tipo	Descripción
Achievement	Naming	unlocked_at (DB) vs unlockedAt (BE) vs dateUnlocked (FE)
Mission	Campos	progress_percentage no existe en frontend
Notification	Status	Enum values diferentes entre capas
Exercise	Type	exercise_type vs type vs exerciseType
Rank	Estructura	Backend anidado, Frontend plano
...	...	...

5.3 Inconsistencias Menores (18)

• snake_case vs camelCase sin transformación consistente
• Campos opcionales tratados como requeridos
• Valores por defecto diferentes entre capas
• Documentación Swagger incompleta

5.4 Tareas Pendientes

Tarea	Prioridad	SP	Descripción
DTO-001	P0	5	Crear tipos canónicos frontend
DTO-002	P0	3	Estandarizar transformación snake/camel
DTO-003	P1	5	Tipar JSONB con discriminated unions
DTO-004	P1	3	Convertir INTERVAL a minutos
DTO-005	P2	8	Generar tipos desde OpenAPI spec

---

6. SISTEMA DE NOTIFICACIONES - 85%

6.1 Email NO IMPLEMENTADO

Archivo: apps/backend/src/modules/notifications/services/notification-sender.service.ts Línea: 353

private async sendEmailNotification(notification: Notification): Promise<void> {
  // TODO: Implementar integración con servicio de email
  // Opciones: SendGrid, AWS SES, Mailgun
  this.logger.warn('Email notifications not implemented yet');
  return;
}

Impacto:

• Notificaciones de tipo email se marcan como enviadas pero no llegan
• Recuperación de contraseña no funciona
• Notificaciones a padres no funcionan

6.2 CRON de Cola No Activo

Archivo: apps/backend/src/modules/notifications/services/notification-queue.service.ts

// @Cron('*/1 * * * *') // Comentado
async processQueue(): Promise<void> {
  // Procesa notificaciones pendientes
}

Problema: Las notificaciones encoladas nunca se procesan automáticamente.

6.3 Tareas Pendientes

Tarea	Prioridad	SP	Descripción
NOTIF-001	P0	5	Integrar servicio de email (SendGrid)
NOTIF-002	P1	2	Habilitar CRON de cola
NOTIF-003	P2	3	Implementar retry con backoff

---

7. SISTEMA DE SETTINGS - 60%

7.1 Preferencias No Cargan de Backend

Archivo: apps/frontend/src/features/student/pages/StudentSettingsPage.tsx Línea: 45

// Carga defaults hardcodeados, no del backend
const defaultPreferences = {
  theme: 'light',
  language: 'es',
  notifications: true,
  sounds: true,
  // ...
};

Debería: Llamar a GET /api/v1/users/me/preferences

7.2 Teacher Preferences No Persisten

Archivo: apps/frontend/src/features/teacher/pages/TeacherSettingsPage.tsx Líneas: 89-102

const handleSave = async () => {
  // Mapeo incorrecto de campos
  await api.patch('/users/me/preferences', {
    notification_email: preferences.emailNotifications, // Campo no existe en backend
    notification_push: preferences.pushNotifications,   // Campo correcto
    // ... más campos mal mapeados
  });
};

Resultado: Algunos campos se guardan, otros se pierden silenciosamente.

7.3 Avatar Upload Placeholder

Archivo: apps/frontend/src/features/shared/components/AvatarUpload.tsx Línea: 67

const uploadAvatar = async (file: File) => {
  // TODO: Implementar upload real a S3/storage
  return 'https://placeholder.com/avatar.png';
};

7.4 Verificación Email No Funciona

Archivo: apps/frontend/src/features/shared/pages/SettingsPage.tsx Línea: 134

const handleVerifyEmail = () => {
  // TODO: Implementar verificación
  toast.info('Verificación de email próximamente');
};

7.5 Tabla user_preferences No Utilizada

Database: Existe auth.user_preferences con estructura completa Backend: No hay endpoints que lean/escriban esta tabla Uso actual: Preferencias en users.metadata JSONB

7.6 Tareas Pendientes

Tarea	Prioridad	SP	Descripción
SETTINGS-001	P0	3	Cargar preferencias desde backend
SETTINGS-002	P0	3	Corregir mapeo teacher preferences
SETTINGS-003	P1	5	Implementar avatar upload a S3
SETTINGS-004	P1	5	Implementar verificación email
SETTINGS-005	P2	3	Migrar a tabla user_preferences

---

8. RESUMEN DE TAREAS PENDIENTES

Por Prioridad

Prioridad	Cantidad	Story Points
P0 - Crítico	15	52
P1 - Alto	18	79
P2 - Medio	12	54
Total	45	185

Por Área

Área	Tareas	SP
Misiones	5	24
Teacher Portal	6	29
Admin Portal	4	18
M4-M5	8	42
DTOs	5	24
Notificaciones	3	10
Settings	5	19
Gamificación Social	6	39
Total	42	205

---

9. PLAN DE ACCIÓN RECOMENDADO

Sprint 7 (Inmediato) - P0

1. MISSION-001/002: Habilitar CRON jobs y rachas (8 SP)
2. TEACHER-001/002: Eliminar mocks y hardcodes (5 SP)
3. DTO-001/002: Tipos canónicos y transformaciones (8 SP)
4. NOTIF-001: Integrar email service (5 SP)
5. SETTINGS-001/002: Corregir preferencias (6 SP)

Total Sprint 7: 32 SP

Sprint 8 - P0/P1

1. M4-001/M5-001: DTOs específicos módulos (10 SP)
2. ADMIN-001: Classrooms desde API (2 SP)
3. M4-002: API fact-checking (8 SP)
4. TEACHER-003/004: Progress y Communication (11 SP)

Total Sprint 8: 31 SP

Sprint 9+ - P1/P2

• Gamificación Social (US-GAM-001 a US-GAM-006)
• Features avanzados M4-M5
• Admin Advanced Page
• Tests y documentación

---

10. MÉTRICAS DE SEGUIMIENTO

KPIs a Monitorear

Métrica	Actual	Objetivo	Fecha
CRON jobs activos	0/3	3/3	Sprint 7
Páginas sin mock data	65%	100%	Sprint 8
DTOs coherentes	62%	95%	Sprint 8
Test coverage	15%	70%	Sprint 10
Features M4-M5	45%	90%	Sprint 9

---

HISTORIAL

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

---

Generado por: Requirements-Analyst Validación: Código fuente real (no documentación) Método: Subagentes especializados por área