workspace/projects/gamilit/orchestration/analisis-frontend-validacion/FASE3-PLAN-IMPLEMENTACIONES.md

FASE 3: PLAN DE IMPLEMENTACIONES Y CORRECCIONES

Fecha: 2025-12-18 Perfil: Requirements Analyst Proyecto: Gamilit

---

RESUMEN DE GAPS A RESOLVER

Prioridad	Cantidad	Descripción
CRÍTICOS	4	Bloquean producción
ALTOS	5	Afectan calidad
MEDIOS	3	Mejoras
TOTAL	12

---

SPRINT 0: CORRECCIONES CRÍTICAS

TASK-001: Integrar Emparejamiento en ExerciseContentRenderer

Prioridad: CRÍTICA Impacto: Respuestas de ejercicios Emparejamiento no renderizan

Archivo a modificar:

• /apps/frontend/src/shared/components/mechanics/ExerciseContentRenderer.tsx

Cambios requeridos:

// Agregar case para 'emparejamiento'
case 'emparejamiento':
  return <EmparejamientoRenderer data={answerData} correct={correctAnswer} showComparison={showComparison} />;

Dependencias:

• Crear componente EmparejamientoRenderer si no existe
• Importar desde features/mechanics/module1/Emparejamiento/

Archivos impactados:

1. ExerciseContentRenderer.tsx - Agregar case
2. Posiblemente crear EmparejamientoRenderer.tsx

Estimación: 2-4 horas

---

TASK-002: Completar Mecánicas Auxiliares (Tipos y Schemas)

Prioridad: CRÍTICA Impacto: 4 mecánicas no son producción-ready

Mecánicas afectadas:

1. ComprensiónAuditiva
2. CollagePrensa
3. TextoEnMovimiento
4. CallToAction

Archivos a crear por cada mecánica:

ComprensiónAuditiva

/features/mechanics/auxiliar/ComprensiónAuditiva/
├── comprensiónAuditivaTypes.ts (CREAR)
├── comprensiónAuditivaSchemas.ts (CREAR)
├── comprensiónAuditivaMockData.ts (CREAR)

CollagePrensa

/features/mechanics/auxiliar/CollagePrensa/
├── collagePrensaTypes.ts (CREAR)
├── collagePrensaSchemas.ts (CREAR)
├── collagePrensa MockData.ts (CREAR)

TextoEnMovimiento

/features/mechanics/auxiliar/TextoEnMovimiento/
├── textoEnMovimientoTypes.ts (CREAR)
├── textoEnMovimientoSchemas.ts (CREAR)
├── textoEnMovimientoMockData.ts (CREAR)

CallToAction

/features/mechanics/auxiliar/CallToAction/
├── callToActionTypes.ts (CREAR)
├── callToActionSchemas.ts (CREAR)
├── callToActionMockData.ts (CREAR)

Dependencias:

• Refactorizar interfaces inline de componentes existentes
• Importar zod para schemas

Archivos impactados:

• 12 archivos nuevos
• 4 componentes existentes (refactorizar imports)

Estimación: 8-12 horas

---

TASK-003: Implementar Gamification API Completo

Prioridad: CRÍTICA Impacto: Solo 20% de endpoints gamification implementados

Archivo a modificar:

• /apps/frontend/src/services/api/gamificationAPI.ts

Endpoints a implementar:

// Endpoints faltantes
export const getUserAchievements = async (userId: string): Promise<Achievement[]> => {
  const response = await apiClient.get(`/gamification/achievements/${userId}`);
  return response.data;
};

export const getUserRanks = async (userId: string): Promise<UserRank> => {
  const response = await apiClient.get(`/gamification/ranks/${userId}`);
  return response.data;
};

export const getLeaderboard = async (params: LeaderboardParams): Promise<LeaderboardEntry[]> => {
  const response = await apiClient.get('/gamification/leaderboard', { params });
  return response.data;
};

export const getUserCoins = async (userId: string): Promise<CoinsStatus> => {
  const response = await apiClient.get(`/gamification/coins/${userId}`);
  return response.data;
};

export const getUserXP = async (userId: string): Promise<XPStatus> => {
  const response = await apiClient.get(`/gamification/xp/${userId}`);
  return response.data;
};

export const claimAchievement = async (userId: string, achievementId: string): Promise<ClaimResult> => {
  const response = await apiClient.post(`/gamification/achievements/${userId}/claim/${achievementId}`);
  return response.data;
};

Dependencias:

• Verificar que endpoints existan en backend
• Crear tipos TypeScript correspondientes
• Agregar error handling

Archivos impactados:

1. gamificationAPI.ts - Agregar funciones
2. Posiblemente crear gamificationTypes.ts

Estimación: 4-6 horas

---

TASK-004: Agregar Tests para Teacher Portal (Crítico)

Prioridad: CRÍTICA Impacto: 97 archivos sin tests, riesgo de regresiones

Estructura de tests a crear:

/apps/frontend/src/apps/teacher/__tests__/
├── hooks/
│   ├── useTeacherDashboard.test.ts
│   ├── useGrading.test.ts
│   ├── useMasteryTracking.test.ts
│   ├── useClassroomRealtime.test.ts
│   ├── useMissionStats.test.ts
├── components/
│   ├── dashboard/
│   │   └── TeacherDashboardStats.test.tsx
│   ├── grading/
│   │   └── RubricEvaluator.test.tsx
│   ├── responses/
│   │   └── ResponseDetailModal.test.tsx
├── pages/
│   ├── TeacherDashboardPage.test.tsx
│   ├── TeacherAssignmentsPage.test.tsx
│   ├── TeacherMonitoringPage.test.tsx

Prioridad de tests:

1. Hooks (core logic)
2. Páginas principales
3. Componentes críticos

Dependencias:

• Configuración Vitest existente
• Mocks para APIs y stores

Estimación: 16-24 horas

---

SPRINT 1: CORRECCIONES ALTAS

TASK-005: Eliminar Páginas Huérfanas y Duplicadas

Prioridad: ALTA Impacto: Código muerto, confusión en mantenimiento

Archivos a ELIMINAR:

/apps/frontend/src/apps/student/pages/
├── GamificationTestPage.tsx (ELIMINAR)
├── GamificationPage.tsx (ELIMINAR - legacy)
├── PasswordRecoveryPage.tsx (ELIMINAR - duplicada)
├── ProfilePage.tsx (ELIMINAR - usar EnhancedProfilePage)
├── LoginPage.tsx (ELIMINAR - usar pages/auth)
├── RegisterPage.tsx (ELIMINAR - usar pages/auth)
├── admin/RolesPermissionsPage.tsx (MOVER a apps/admin/)
├── admin/UserManagementPage.tsx (MOVER a apps/admin/)

Archivo a EVALUAR:

• NewLeaderboardPage.tsx - Comparar con LeaderboardPage actual

Dependencias:

• Verificar que no hay imports a estos archivos
• Actualizar rutas si es necesario

Archivos impactados:

• 8 archivos a eliminar
• 2 archivos a mover
• Posibles imports a actualizar

Estimación: 2-4 horas

---

TASK-006: Implementar Schemas Module 2

Prioridad: ALTA Impacto: Validación débil en 4 mecánicas

Archivos a crear:

/features/mechanics/module2/
├── LecturaInferencial/lecturaInferencialSchemas.ts (CREAR)
├── PuzzleContexto/puzzleContextoSchemas.ts (CREAR)
├── PrediccionNarrativa/prediccionNarrativaSchemas.ts (CREAR)
├── ConstruccionHipotesis/construccionHipotesisSchemas.ts (CREAR)

Patrón a seguir (de DetectiveTextual):

import { z } from 'zod';

export const lecturaInferencialAnswerSchema = z.object({
  selectedOption: z.string(),
  timestamp: z.number(),
  // ... otros campos según tipo
});

export const lecturaInferencialExerciseSchema = z.object({
  id: z.string(),
  type: z.literal('lectura_inferencial'),
  // ... estructura del ejercicio
});

export type LecturaInferencialAnswer = z.infer<typeof lecturaInferencialAnswerSchema>;

Dependencias:

• Importar zod
• Revisar tipos existentes para estructura

Archivos impactados:

• 4 archivos nuevos
• Posiblemente actualizar imports en componentes

Estimación: 4-6 horas

---

TASK-007: Agregar Error Handling a APIs Pendientes

Prioridad: ALTA Impacto: UX pobre en errores

Archivos a modificar:

1. profileAPI.ts
2. passwordAPI.ts
3. schoolsAPI.ts
4. missionsAPI.ts

Patrón a implementar:

import { handleAPIError } from './apiErrorHandler';

export const updateProfile = async (userId: string, data: ProfileData) => {
  try {
    const response = await apiClient.put(`/users/${userId}/profile`, data);
    return response.data;
  } catch (error) {
    throw handleAPIError(error);
  }
};

Dependencias:

• apiErrorHandler.ts ya existe

Archivos impactados:

• 4 archivos a modificar

Estimación: 2-3 horas

---

TASK-008: Tests para Mechanics

Prioridad: ALTA Impacto: 80+ archivos sin tests

Estructura de tests a crear:

/features/mechanics/__tests__/
├── module1/
│   ├── VerdaderoFalso.test.tsx
│   ├── Crucigrama.test.tsx
│   ├── SopaLetras.test.tsx
│   ├── Emparejamiento.test.tsx
│   ├── Timeline.test.tsx
├── module2/
│   ├── DetectiveTextual.test.tsx
│   ├── RuedaInferencias.test.tsx
├── module3/
│   ├── AnalisisFuentes.test.tsx
│   ├── PodcastArgumentativo.test.tsx
├── shared/
│   └── ExerciseContentRenderer.test.tsx

Prioridad de tests:

1. ExerciseContentRenderer (crítico)
2. Mecánicas Module 1 (base)
3. Mecánicas Module 3 (producción)

Estimación: 12-16 horas

---

TASK-009: Tests para Assignments

Prioridad: ALTA Impacto: 15 archivos sin tests

Estructura:

/features/assignments/__tests__/
├── hooks/
│   └── useAssignments.test.ts
├── components/
│   └── AssignmentCard.test.tsx
├── api/
│   └── assignmentsApi.test.ts

Estimación: 6-8 horas

---

SPRINT 2: MEJORAS

TASK-010: Completar Páginas Teacher en Construcción

Prioridad: MEDIA Impacto: Funcionalidad pendiente

Archivos a completar:

1. TeacherContentPage.tsx - Remover flag SHOW_UNDER_CONSTRUCTION
2. TeacherResourcesPage.tsx - Implementar funcionalidad

Dependencias:

• Definir requerimientos de estas páginas
• Verificar APIs necesarias

Estimación: 8-16 horas (depende de alcance)

---

TASK-011: Agregar Mock Data Faltante

Prioridad: MEDIA Impacto: Testing difícil

Archivos a crear:

/features/mechanics/
├── module2/LecturaInferencial/lecturaInferencialMockData.ts (CREAR)
├── module2/ConstruccionHipotesis/construccionHipotesisMockData.ts (CREAR)

Patrón:

export const lecturaInferencialMockExercise = {
  id: 'mock-li-001',
  type: 'lectura_inferencial',
  title: 'Ejercicio de prueba',
  // ... estructura completa
};

export const lecturaInferencialMockData = [
  lecturaInferencialMockExercise,
  // más ejemplos
];

Estimación: 2-4 horas

---

TASK-012: Conectar analyticsInterceptor

Prioridad: MEDIA Impacto: Métricas perdidas

Archivo a modificar:

• /apps/frontend/src/services/api/apiInterceptors.ts

Cambios:

// Conectar a servicio de analytics real
export const analyticsInterceptor = {
  onRequest: (config) => {
    analyticsService.trackAPICall({
      endpoint: config.url,
      method: config.method,
      timestamp: Date.now()
    });
    return config;
  },
  onResponse: (response) => {
    analyticsService.trackAPIResponse({
      endpoint: response.config.url,
      status: response.status,
      duration: Date.now() - response.config.metadata?.startTime
    });
    return response;
  }
};

Dependencias:

• Definir analyticsService
• Decidir destino de métricas

Estimación: 2-4 horas

---

MATRIZ DE DEPENDENCIAS

TASK-001 (Emparejamiento ECR)
    └── No tiene dependencias

TASK-002 (Mecánicas Auxiliares)
    └── No tiene dependencias

TASK-003 (Gamification API)
    └── Depende de: Backend endpoints existentes

TASK-004 (Tests Teacher)
    └── No tiene dependencias

TASK-005 (Eliminar páginas)
    └── Depende de: Verificar imports

TASK-006 (Schemas Module 2)
    └── No tiene dependencias

TASK-007 (Error Handling APIs)
    └── No tiene dependencias

TASK-008 (Tests Mechanics)
    └── Depende de: TASK-001 (Emparejamiento)

TASK-009 (Tests Assignments)
    └── No tiene dependencias

TASK-010 (Páginas Teacher)
    └── Depende de: Definición de requerimientos

TASK-011 (Mock Data)
    └── Depende de: TASK-006 (Schemas)

TASK-012 (Analytics)
    └── Depende de: Definición de analyticsService

---

CRONOGRAMA SUGERIDO

Semana 1: Sprint 0 - Críticos

Día	Tasks	Horas
1-2	TASK-001, TASK-002	12-16h
3	TASK-003	4-6h
4-5	TASK-004 (inicio)	8-12h

Semana 2: Sprint 1 - Altos

Día	Tasks	Horas
1	TASK-005, TASK-006	6-10h
2	TASK-007	2-3h
3-5	TASK-004 (cont), TASK-008	16-20h

Semana 3: Sprint 2 - Mejoras

Día	Tasks	Horas
1-2	TASK-009	6-8h
3-4	TASK-010, TASK-011	10-20h
5	TASK-012	2-4h

---

ESTIMACIÓN TOTAL

Sprint	Tasks	Horas Est.
Sprint 0	4	30-48h
Sprint 1	5	26-37h
Sprint 2	3	18-36h
TOTAL	12	74-121h

---

Estado: FASE 3 COMPLETADA Siguiente: FASE 4 - Validación de Planeación vs Análisis