workspace/projects/gamilit/docs/90-transversal/api/API-TEACHER-MODULE.md

API TEACHER MODULE

Proyecto: GAMILIT - Plataforma Educativa Gamificada Modulo: Teacher Version: 1.0 Fecha: 2025-12-23 Generado por: Auditoria de Documentacion

---

RESUMEN

Metrica	Valor
Controllers	8
Services	16
Endpoints	50+
Roles requeridos	admin_teacher, super_admin

---

CONTROLLERS

1. TeacherController - Controlador principal
2. TeacherClassroomsController - Gestion de aulas
3. TeacherGradesController - Calificaciones
4. TeacherContentController - Contenido educativo
5. TeacherCommunicationController - Comunicacion
6. InterventionAlertsController - Alertas de intervencion
7. ManualReviewController - Revision manual
8. ExerciseResponsesController - Respuestas de ejercicios

---

1. DASHBOARD ENDPOINTS

GET /teacher/dashboard/stats

Descripcion: Obtiene estadisticas del aula

Response:

{
  "totalStudents": 25,
  "activeStudents": 22,
  "averageProgress": 75.5,
  "pendingSubmissions": 12
}

GET /teacher/dashboard/activities

Descripcion: Obtiene actividades recientes

Query params:

• limit (optional): Numero de actividades (default: 10)

GET /teacher/dashboard/alerts

Descripcion: Obtiene alertas de estudiantes

GET /teacher/dashboard/top-performers

Descripcion: Obtiene mejores estudiantes

Query params:

• limit (optional): Numero de estudiantes (default: 5)

GET /teacher/dashboard/module-progress

Descripcion: Resumen de progreso por modulo

---

2. STUDENT PROGRESS ENDPOINTS

GET /teacher/students/:studentId/progress

Descripcion: Obtiene progreso completo del estudiante

Query params:

• moduleId (optional): Filtrar por modulo
• startDate (optional): Fecha inicio
• endDate (optional): Fecha fin

GET /teacher/students/:studentId/overview

Descripcion: Vista general del estudiante

GET /teacher/students/:studentId/stats

Descripcion: Estadisticas del estudiante

GET /teacher/students/:studentId/notes

Descripcion: Obtiene notas del maestro sobre el estudiante

POST /teacher/students/:studentId/note

Descripcion: Agrega o actualiza nota sobre estudiante

Body:

{
  "classroomId": "uuid",
  "content": "Nota del maestro",
  "type": "observation|concern|praise"
}

GET /teacher/students/:studentId/insights

Descripcion: Insights con IA sobre el estudiante

Response:

{
  "strengths": ["...", "..."],
  "weaknesses": ["...", "..."],
  "predictions": {...},
  "recommendations": ["...", "..."]
}

---

3. GRADING ENDPOINTS

GET /teacher/submissions

Descripcion: Obtiene envios con filtros

Query params:

• assignmentId (optional)
• classroomId (optional)
• studentId (optional)
• status (optional): pending|graded|returned
• moduleId (optional)
• page (optional)
• limit (optional)
• sortBy (optional)
• sortOrder (optional): asc|desc

GET /teacher/submissions/:id

Descripcion: Obtiene detalle de un envio

POST /teacher/submissions/:submissionId/feedback

Descripcion: Envia retroalimentacion

Body:

{
  "score": 85,
  "feedback": "Buen trabajo...",
  "rubricScores": {...}
}

POST /teacher/submissions/bulk-grade

Descripcion: Califica multiples envios

Body:

{
  "submissions": [
    {"id": "uuid1", "score": 90, "feedback": "..."},
    {"id": "uuid2", "score": 85, "feedback": "..."}
  ]
}

---

4. ANALYTICS ENDPOINTS

GET /teacher/analytics

Descripcion: Analiticas generales del aula

Query params:

• classroomId (optional)
• startDate (optional)
• endDate (optional)
• groupBy (optional): day|week|month

GET /teacher/analytics/classroom/:id

Descripcion: Analiticas de un aula especifica

GET /teacher/analytics/assignment/:id

Descripcion: Analiticas de una asignacion

GET /teacher/analytics/engagement

Descripcion: Metricas de compromiso

GET /teacher/analytics/reports

Descripcion: Genera reportes comprehensivos

GET /teacher/analytics/economy

Descripcion: Analiticas de economia ML Coins

Response:

{
  "totalCirculation": 50000,
  "averageBalance": 200,
  "distributionByRange": {...},
  "topEarners": [...],
  "wealthDistribution": {...}
}

GET /teacher/analytics/students-economy

Descripcion: Datos de economia por estudiante

GET /teacher/analytics/achievements

Descripcion: Estadisticas de logros

---

5. REPORT GENERATION ENDPOINTS

POST /teacher/reports/generate

Descripcion: Genera reporte de insights (PDF/Excel)

Body:

{
  "classroomId": "uuid",
  "format": "pdf|excel",
  "includeInsights": true,
  "studentIds": ["uuid1", "uuid2"] // optional
}

Response: Archivo binario (PDF o XLSX)

Nota Tecnica (P0-04): Los PDFs se generan usando Puppeteer (headless Chrome) para renderizado de alta fidelidad con graficas y estilos CSS. El proceso:

1. Renderiza HTML con datos del reporte
2. Captura como PDF con Puppeteer
3. Retorna archivo binario con headers de descarga

GET /teacher/reports/recent

Descripcion: Obtiene reportes recientes

Query params:

• limit (optional): Numero de reportes (default: 10)

GET /teacher/reports/stats

Descripcion: Estadisticas de reportes generados

GET /teacher/reports/:id/download

Descripcion: Descarga un reporte previamente generado

---

6. BONUS ML COINS

POST /teacher/students/:studentId/bonus

Descripcion: Otorga ML Coins bonus a estudiante

Body:

{
  "amount": 50,
  "reason": "Excelente participacion en clase"
}

Response:

{
  "success": true,
  "newBalance": 350,
  "transactionId": "uuid"
}

---

7. CLASSROOMS ENDPOINTS

GET /teacher/classrooms

Descripcion: Lista aulas del maestro

GET /teacher/classrooms/:id

Descripcion: Detalle de un aula

GET /teacher/classrooms/:id/students

Descripcion: Lista estudiantes del aula

GET /teacher/classrooms/:id/stats

Descripcion: Estadisticas del aula

GET /teacher/classrooms/:id/progress

Descripcion: Progreso del aula

GET /teacher/classrooms/:classroomId/teachers

Descripcion: Maestros asignados al aula

GET /teacher/classrooms/:classroomId/students/:studentId/permissions

Descripcion: Permisos de un estudiante

PATCH /teacher/classrooms/:classroomId/students/:studentId/permissions

Descripcion: Actualiza permisos de estudiante

POST /teacher/classrooms/:classroomId/students/:studentId/block

Descripcion: Bloquea a un estudiante

POST /teacher/classrooms/:classroomId/students/:studentId/unblock

Descripcion: Desbloquea a un estudiante

---

8. COMMUNICATION ENDPOINTS

GET /teacher/conversations

Descripcion: Lista conversaciones

Response:

{
  "conversations": [
    {
      "id": "uuid",
      "participants": ["Juan Perez", "Maria Garcia"],
      "lastMessage": "...",
      "unreadCount": 2
    }
  ]
}

Nota (P2-04): Los nombres de participantes ahora muestran nombres reales obtenidos de auth.profiles en lugar de identificadores truncados como "User_abc123".

GET /teacher/unread-count

Descripcion: Cuenta mensajes no leidos

POST /teacher/classroom/:classroomId/announcement

Descripcion: Envia anuncio al aula

Body:

{
  "title": "Titulo del anuncio",
  "content": "Contenido del anuncio",
  "priority": "normal|high"
}

---

9. INTERVENTION ALERTS ENDPOINTS

GET /teacher/alerts

Descripcion: Lista alertas de intervencion

GET /teacher/alerts/:id

Descripcion: Detalle de una alerta

PATCH /teacher/alerts/:id/acknowledge

Descripcion: Reconoce una alerta

PATCH /teacher/alerts/:id/resolve

Descripcion: Resuelve una alerta

PATCH /teacher/alerts/:id/dismiss

Descripcion: Descarta una alerta

---

10. MANUAL REVIEW ENDPOINTS

GET /teacher/pending

Descripcion: Ejercicios pendientes de revision manual

GET /teacher/my-reviews

Descripcion: Mis revisiones

POST /teacher/:id/start

Descripcion: Inicia revision

POST /teacher/:id/complete

Descripcion: Completa revision

POST /teacher/:id/return

Descripcion: Devuelve para correccion

---

11. EXERCISE RESPONSES ENDPOINTS

GET /teacher/exercises/:exerciseId/responses

Descripcion: Respuestas de un ejercicio

GET /teacher/attempts

Descripcion: Lista paginada de intentos con estadisticas agregadas

Query params:

• page (optional): Numero de pagina (default: 1)
• limit (optional): Items por pagina (default: 20, max: 100)
• student_id (optional): Filtrar por UUID de estudiante
• exercise_id (optional): Filtrar por UUID de ejercicio
• module_id (optional): Filtrar por UUID de modulo
• classroom_id (optional): Filtrar por UUID de aula
• from_date (optional): Fecha inicio (ISO 8601)
• to_date (optional): Fecha fin (ISO 8601)
• is_correct (optional): Filtrar por resultado (true/false)
• student_search (optional): Buscar por nombre/email de estudiante
• sort_by (optional): Campo de ordenamiento (submitted_at|score|time)
• sort_order (optional): Orden (asc|desc, default: desc)

Response:

{
  "data": [
    {
      "id": "uuid",
      "student_id": "uuid",
      "student_name": "Juan Perez",
      "exercise_id": "uuid",
      "exercise_title": "Comprension Lectora - Texto Narrativo",
      "module_name": "Modulo 1: Lectura Literal",
      "attempt_number": 1,
      "submitted_answers": {"answers": ["A", "B", "C"]},
      "is_correct": true,
      "score": 85,
      "time_spent_seconds": 120,
      "hints_used": 2,
      "comodines_used": ["pistas", "vision_lectora"],
      "xp_earned": 50,
      "ml_coins_earned": 10,
      "submitted_at": "2024-11-24T10:30:00Z"
    }
  ],
  "total": 150,
  "page": 1,
  "limit": 20,
  "total_pages": 8,
  "stats": {
    "total_attempts": 150,
    "correct_count": 120,
    "incorrect_count": 30,
    "average_score": 78,
    "success_rate": 80
  }
}

Nota (P2-03): Las estadisticas (stats) se calculan en el servidor para optimizar performance del cliente.

GET /teacher/attempts/:id

Descripcion: Detalle de un intento (incluye respuesta correcta y tipo de ejercicio)

Response:

{
  "id": "uuid",
  "student_id": "uuid",
  "student_name": "Juan Perez",
  "exercise_id": "uuid",
  "exercise_title": "Comprension Lectora",
  "correct_answer": {"correct_answers": ["A", "C", "D"]},
  "exercise_type": "multiple_choice",
  "max_score": 100,
  "...otros campos de AttemptResponseDto"
}

GET /teacher/attempts/student/:studentId

Descripcion: Intentos de un estudiante especifico

GET /teacher/student/:studentId/history

Descripcion: Historial del estudiante

POST /teacher/student/:studentId/feedback

Descripcion: Envia retroalimentacion

---

12. CONTENT MANAGEMENT

POST /teacher/content/generate

Descripcion: Genera contenido educativo

GET /teacher/content/:id

Descripcion: Obtiene contenido

POST /teacher/content/:id/clone

Descripcion: Clona contenido

PATCH /teacher/content/:id/publish

Descripcion: Publica contenido

DELETE /teacher/content/:id

Descripcion: Elimina contenido

---

AUTENTICACION Y AUTORIZACION

Todos los endpoints requieren:

• Header: Authorization: Bearer <jwt_token>
• Roles permitidos: admin_teacher, super_admin

---

CODIGOS DE RESPUESTA

Codigo	Descripcion
200	Exito
201	Creado
400	Solicitud invalida
401	No autenticado
403	No autorizado
404	No encontrado
500	Error del servidor

---

SERVICES DEL MODULO

1. TeacherDashboardService
2. StudentProgressService
3. GradingService
4. AnalyticsService
5. ReportsService
6. BonusCoinsService
7. StorageService
8. TeacherReportsService
9. ManualReviewService
10. InterventionAlertsService
11. ExerciseResponsesService
12. TeacherClassroomsCrudService
13. TeacherMessagesService
14. TeacherContentService
15. StudentBlockingService
16. MlPredictorService

---

Generado por: Requirements-Analyst Fecha: 2025-12-23 Version: 1.0