workspace/projects/gamilit/docs/90-transversal/restructuracion-v2/API-MAPPING-TEACHER-MONITORING.md

Teacher Monitoring Endpoints - Mapping Guide

Fecha: 2025-11-26 Contexto: ISS-004, ISS-005, ISS-006 (P2) Decisión: Documentar alternativas existentes (NO crear endpoints duplicados)

---

📋 Resumen

Durante la validación del Portal Teacher se identificaron 3 endpoints "faltantes" que en realidad tienen alternativas funcionales existentes. Este documento mapea las rutas solicitadas a las alternativas disponibles.

---

🗺️ Mapeo de Endpoints

1. Activity Monitoring

Solicitado	GET /teacher/monitoring/activity
Usar	GET /teacher/dashboard/activities
Controller	TeacherController
Service	TeacherDashboardService.getRecentActivities()

Ejemplo de uso:

GET /api/v1/teacher/dashboard/activities?limit=20

# Response: RecentActivity[]
{
  "data": [
    {
      "id": "uuid",
      "student_name": "Juan Pérez",
      "student_id": "uuid",
      "activity_type": "submission",
      "title": "Ejercicio Módulo 1",
      "timestamp": "2025-11-26T10:30:00Z",
      "status": "pending"
    }
  ]
}

Parámetros:

• limit (opcional): Número de actividades a retornar (default: 10)

---

2. Real-time Monitoring

Solicitado	GET /teacher/monitoring/realtime
Usar	GET /teacher/dashboard/stats
Controller	TeacherController
Service	TeacherDashboardService.getClassroomStats()

Ejemplo de uso:

GET /api/v1/teacher/dashboard/stats

# Response: ClassroomStats
{
  "total_students": 45,
  "active_students": 38,
  "average_score": 78.5,
  "average_completion": 65.2,
  "total_submissions_pending": 12,
  "students_at_risk": 3
}

Datos "realtime" incluidos:

• total_submissions_pending: Submissions con status 'submitted' o 'pending'
• active_students: Actividad en últimos 7 días
• students_at_risk: Estudiantes con score < 60 o inactivos

---

3. Progress Overview

Solicitado	GET /teacher/progress/overview
Usar	Múltiples opciones según contexto

Opción A: Por módulo (general)

GET /api/v1/teacher/dashboard/module-progress

# Response: ModuleProgressSummary[]
{
  "data": [
    {
      "module_id": "uuid",
      "module_name": "Módulo 1: Comprensión Literal",
      "students_active": 35,
      "average_completion": 72.3
    }
  ]
}

Opción B: Por classroom (detallado)

GET /api/v1/teacher/classrooms/:classroomId/progress

# Response:
{
  "classroomData": {
    "id": "uuid",
    "name": "5to Grado A",
    "student_count": 30,
    "active_students": 28,
    "average_completion": 68.5,
    "average_score": 75.2,
    "total_exercises": 50,
    "completed_exercises": 890
  },
  "moduleProgress": [...]
}

Opción C: Por estudiante

GET /api/v1/teacher/students/:studentId/progress

# Response: StudentProgressDetail
{
  "student_overview": {...},
  "stats": {...},
  "modules": [...],
  "recent_activity": [...],
  "struggle_areas": [...],
  "class_comparison": {...}
}

---

📊 Tabla de Servicios

Endpoint	Service	Método
/dashboard/activities	TeacherDashboardService	getRecentActivities()
/dashboard/stats	TeacherDashboardService	getClassroomStats()
/dashboard/module-progress	TeacherDashboardService	getModuleProgressSummary()
/classrooms/:id/progress	TeacherClassroomsCrudService	getClassroomProgress()
/students/:id/progress	StudentProgressService	getStudentProgress()

---

📁 Ubicaciones en Codebase

apps/backend/src/modules/teacher/
├── controllers/
│   ├── teacher.controller.ts           # Endpoints dashboard/*
│   └── teacher-classrooms.controller.ts # Endpoints classrooms/*
├── services/
│   ├── teacher-dashboard.service.ts    # Stats, activities, module-progress
│   ├── student-progress.service.ts     # Student progress detail
│   └── teacher-classrooms-crud.service.ts # Classroom progress
└── dto/
    └── analytics.dto.ts               # DTOs relacionados

---

✅ Justificación de la Decisión

¿Por qué NO crear los endpoints solicitados?

1. Redundancia: Ya existen endpoints equivalentes consolidados
2. API Design: Single source of truth para cada funcionalidad
3. Mantenimiento: Evitar duplicación de lógica y código
4. Frontend: Ya consume las rutas existentes correctamente

---

Documentado por: Architecture-Analyst Fecha: 2025-11-26