rckrdmrd
00c09054e8
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>
443 lines
9.3 KiB
Markdown
443 lines
9.3 KiB
Markdown
# 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:**
|
|
```json
|
|
{
|
|
"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:**
|
|
```json
|
|
{
|
|
"classroomId": "uuid",
|
|
"content": "Nota del maestro",
|
|
"type": "observation|concern|praise"
|
|
}
|
|
```
|
|
|
|
### GET /teacher/students/:studentId/insights
|
|
**Descripcion:** Insights con IA sobre el estudiante
|
|
|
|
**Response:**
|
|
```json
|
|
{
|
|
"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:**
|
|
```json
|
|
{
|
|
"score": 85,
|
|
"feedback": "Buen trabajo...",
|
|
"rubricScores": {...}
|
|
}
|
|
```
|
|
|
|
### POST /teacher/submissions/bulk-grade
|
|
**Descripcion:** Califica multiples envios
|
|
|
|
**Body:**
|
|
```json
|
|
{
|
|
"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:**
|
|
```json
|
|
{
|
|
"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:**
|
|
```json
|
|
{
|
|
"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:**
|
|
```json
|
|
{
|
|
"amount": 50,
|
|
"reason": "Excelente participacion en clase"
|
|
}
|
|
```
|
|
|
|
**Response:**
|
|
```json
|
|
{
|
|
"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:**
|
|
```json
|
|
{
|
|
"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
|