rckrdmrd/workspace
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
11f43c0be9
workspace/projects/gamilit/docs/90-transversal/api/API-TEACHER-MODULE.md
rckrdmrd 00c09054e8 docs: Auditoria documentacion vs desarrollo - Correcciones P0 completas 
Analisis exhaustivo comparando documentacion con codigo real.

## Documentacion actualizada:
- FEATURES-IMPLEMENTADAS.md: Metricas reales (76 controllers, 103 services, 497 componentes)
- docs/README.md: Estadisticas actualizadas
- API.md: Secciones Teacher Portal API y Social Features

## Documentacion nueva:
- API-TEACHER-MODULE.md: 50+ endpoints del modulo Teacher
- docs/frontend/student/README.md: 24 paginas documentadas
- TABLAS-NUEVAS-2025-12.md: 6 tablas nuevas (parent_*, user_purchases, teacher_interventions)

## Limpieza de codigo:
- Eliminados archivos huerfanos en student/pages/admin/ (no importados)

## Hallazgos:
- Patron Component/Page en Teacher es arquitectura intencional (no duplicados)
- admin/pages/ tiene versiones completas y activas

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2025-12-23 08:03:56 -06:00

9.3 KiB
Raw Blame History

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)

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

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 intentos de ejercicios

GET /teacher/attempts/:id

Descripcion: Detalle de un intento

GET /teacher/attempts/student/:studentId

Descripcion: Intentos de un estudiante

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