rckrdmrd/workspace
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
0f29d35578
workspace/projects/gamilit/docs/90-transversal/api/API-ADMIN-MODULE.md
rckrdmrd 11f43c0be9 docs: Correcciones P1 - Admin API, Triggers inventory, Master inventory 
## Documentacion nueva:
- API-ADMIN-MODULE.md: 22 controllers, 150+ endpoints documentados
- TRIGGERS-INVENTORY.md: 111 triggers de BD documentados por schema

## Actualizaciones:
- MASTER_INVENTORY.yml v4.0.0: Metricas corregidas
  - Database: 15 schemas, 132 tablas, 111 triggers
  - Backend: 16 modulos, 103 services, 76 controllers
  - Frontend: 497 componentes, 102 hooks, 64 paginas
- API.md: Seccion Admin Portal API agregada
- LOG-IMPLEMENTACION.md: P1-001 a P1-003 completados

Progreso auditoria: P0 100%, P1 43%

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

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2025-12-26 12:34:33 -06:00

15 KiB
Raw Blame History

API ADMIN MODULE

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

RESUMEN

Metrica Valor
Controllers 22
Services 22
Endpoints 150+
Entidades 6
Roles requeridos super_admin

CONTROLLERS

  1. AdminAlertsController - Sistema de alertas
  2. AdminAnalyticsController - Analisis y reportes
  3. AdminAssignmentsController - Gestion de asignaciones
  4. AdminBulkOperationsController - Operaciones masivas
  5. AdminContentController - Gestion de contenido
  6. AdminDashboardController - Dashboard principal
  7. AdminDashboardActivityController - Actividad del dashboard
  8. AdminDashboardStatsController - Estadisticas del dashboard
  9. AdminGamificationConfigController - Configuracion de gamificacion
  10. AdminInterventionsController - Alertas de intervencion
  11. AdminLogsController - Logs del sistema
  12. AdminMonitoringController - Monitoreo del sistema
  13. AdminOrganizationsController - Gestion de organizaciones
  14. AdminProgressController - Seguimiento de progreso
  15. AdminReportsController - Reportes
  16. AdminRolesController - Roles y permisos
  17. AdminSystemController - Sistema y configuracion
  18. AdminUserStatsController - Estadisticas de usuarios
  19. AdminUsersController - Gestion de usuarios
  20. ClassroomAssignmentsController - Asignacion de aulas
  21. ClassroomTeachersRestController - REST API aulas-profesores
  22. FeatureFlagsController - Feature flags

1. DASHBOARD ENDPOINTS

GET /admin/dashboard

Descripcion: Dashboard completo con estadisticas agregadas

GET /admin/dashboard/stats

Descripcion: Solo estadisticas del sistema

GET /admin/dashboard/recent-activity

Descripcion: Actividad reciente del sistema

GET /admin/dashboard/user-stats

Descripcion: Estadisticas de usuarios

GET /admin/dashboard/organization-stats

Descripcion: Estadisticas de organizaciones

GET /admin/dashboard/moderation-queue

Descripcion: Cola de moderacion de contenido

GET /admin/dashboard/classroom-overview

Descripcion: Vista general de aulas

GET /admin/dashboard/assignment-stats

Descripcion: Estadisticas de asignaciones

GET /admin/dashboard/actions/recent

Descripcion: Acciones administrativas recientes

GET /admin/dashboard/alerts

Descripcion: Alertas activas del sistema

GET /admin/dashboard/analytics/user-activity

Descripcion: Analiticas de actividad de usuarios

2. USERS ENDPOINTS

GET /admin/users

Descripcion: Listar usuarios con filtros y paginacion

Query params:

  • page (optional)
  • limit (optional)
  • role (optional): student, admin_teacher, super_admin
  • status (optional): active, suspended, inactive
  • search (optional): busqueda por nombre/email

GET /admin/users/:id

Descripcion: Obtener detalles del usuario

GET /admin/users/stats

Descripcion: Estadisticas detalladas de usuarios

PUT /admin/users/:id

Descripcion: Actualizar usuario

DELETE /admin/users/:id

Descripcion: Eliminar usuario

POST /admin/users/:id/suspend

Descripcion: Suspender usuario

POST /admin/users/:id/activate

Descripcion: Activar usuario suspendido

POST /admin/users/:id/deactivate

Descripcion: Desactivar usuario

POST /admin/users/:id/reset-password

Descripcion: Forzar reseteo de contrasena

3. BULK OPERATIONS ENDPOINTS

POST /admin/bulk-operations/suspend-users

Descripcion: Suspender multiples usuarios

Body:

{
  "userIds": ["uuid1", "uuid2", "uuid3"],
  "reason": "Motivo de suspension"
}

POST /admin/bulk-operations/activate-users

Descripcion: Activar multiples usuarios

POST /admin/bulk-operations/update-role

Descripcion: Actualizar roles masivamente

POST /admin/bulk-operations/delete-users

Descripcion: Eliminar multiples usuarios

GET /admin/bulk-operations/:id

Descripcion: Obtener estado de operacion

GET /admin/bulk-operations

Descripcion: Listar operaciones recientes

4. ORGANIZATIONS ENDPOINTS

GET /admin/organizations

Descripcion: Listar organizaciones/tenants

GET /admin/organizations/:id

Descripcion: Obtener organizacion

POST /admin/organizations

Descripcion: Crear organizacion

PUT /admin/organizations/:id

Descripcion: Actualizar organizacion

DELETE /admin/organizations/:id

Descripcion: Eliminar organizacion

GET /admin/organizations/:id/stats

Descripcion: Estadisticas de organizacion

GET /admin/organizations/:id/users

Descripcion: Usuarios de organizacion

PATCH /admin/organizations/:id/subscription

Descripcion: Actualizar suscripcion

PATCH /admin/organizations/:id/features

Descripcion: Actualizar feature flags de org

5. CONTENT MANAGEMENT ENDPOINTS

GET /admin/content/pending

Descripcion: Contenido pendiente de aprobacion

GET /admin/content/exercises/pending

Descripcion: Ejercicios pendientes

POST /admin/content/:id/approve

Descripcion: Aprobar contenido

POST /admin/content/:id/reject

Descripcion: Rechazar contenido

POST /admin/content/version

Descripcion: Crear snapshot de version

GET /admin/content/media

Descripcion: Obtener libreria de medios

DELETE /admin/content/media/:id

Descripcion: Eliminar archivo de media

GET /admin/content/approval-history

Descripcion: Historial de aprobaciones

6. GAMIFICATION CONFIG ENDPOINTS

GET /admin/gamification/settings

Descripcion: Obtener configuracion actual de gamificacion

PUT /admin/gamification/settings

Descripcion: Actualizar configuracion

POST /admin/gamification/settings/preview

Descripcion: Previsualizar impacto de cambios

POST /admin/gamification/restore-defaults

Descripcion: Restaurar valores por defecto

GET /admin/gamification/parameters

Descripcion: Listar parametros por categoria

GET /admin/gamification/parameters/:id

Descripcion: Obtener parametro por ID

PUT /admin/gamification/parameters/:id

Descripcion: Actualizar parametro

GET /admin/gamification/maya-ranks

Descripcion: Obtener configuracion de rangos Maya

PUT /admin/gamification/maya-ranks/:rankName

Descripcion: Actualizar umbral de rango Maya

7. ANALYTICS ENDPOINTS

GET /admin/analytics/overview

Descripcion: Vista general de analiticas

GET /admin/analytics/engagement

Descripcion: Analiticas de engagement por segmento

GET /admin/analytics/gamification

Descripcion: Distribucion de XP, rangos y niveles

GET /admin/analytics/activity-timeline

Descripcion: Linea de tiempo de actividad

Query params:

  • days (optional): Ultimos N dias (default: 30)

GET /admin/analytics/top-users

Descripcion: Top usuarios por metrica

Query params:

  • metric (optional): xp, exercises, streak
  • limit (optional): default 10

GET /admin/analytics/retention

Descripcion: Retencion por cohorte (12 meses)

GET /admin/analytics/export

Descripcion: Exportar analiticas a CSV

8. PROGRESS TRACKING ENDPOINTS

GET /admin/progress/overview

Descripcion: Vista general del sistema

GET /admin/progress/classrooms/:id

Descripcion: Progreso detallado de aula

GET /admin/progress/students/:id

Descripcion: Progreso detallado de estudiante

GET /admin/progress/students/:id/achievements

Descripcion: Logros de estudiante

GET /admin/progress/modules/:id

Descripcion: Estadisticas del modulo

GET /admin/progress/exercises/:id

Descripcion: Estadisticas del ejercicio

GET /admin/progress/export

Descripcion: Exportar datos de progreso a CSV

9. ALERTS ENDPOINTS

GET /admin/alerts

Descripcion: Listar alertas con filtros

GET /admin/alerts/stats/summary

Descripcion: Estadisticas de alertas

GET /admin/alerts/:id

Descripcion: Obtener alerta por ID

POST /admin/alerts

Descripcion: Crear alerta manual

PATCH /admin/alerts/:id/acknowledge

Descripcion: Reconocer alerta

PATCH /admin/alerts/:id/resolve

Descripcion: Resolver alerta

PATCH /admin/alerts/:id/suppress

Descripcion: Suprimir alerta

10. INTERVENTIONS ENDPOINTS

GET /admin/interventions

Descripcion: Listar alertas de intervencion

GET /admin/interventions/:id

Descripcion: Obtener alerta por ID

PATCH /admin/interventions/:id/acknowledge

Descripcion: Reconocer alerta

PATCH /admin/interventions/:id/resolve

Descripcion: Resolver alerta

DELETE /admin/interventions/:id/dismiss

Descripcion: Descartar alerta

11. SYSTEM ENDPOINTS

GET /admin/system/health

Descripcion: Estado de salud del sistema

GET /admin/system/metrics

Descripcion: Metricas del sistema

GET /admin/system/audit-log

Descripcion: Log de auditoria

GET /admin/system/config

Descripcion: Obtener configuracion

GET /admin/system/config/:category

Descripcion: Configuracion por categoria

PUT /admin/system/config/:category

Descripcion: Actualizar configuracion por categoria

POST /admin/system/maintenance

Descripcion: Alternar modo mantenimiento

POST /admin/system/maintenance/cleanup-logs

Descripcion: Limpiar logs antiguos

POST /admin/system/maintenance/cleanup-activity

Descripcion: Limpiar logs de actividad

POST /admin/system/maintenance/optimize-database

Descripcion: Optimizar base de datos

POST /admin/system/maintenance/clear-cache

Descripcion: Limpiar cache

POST /admin/system/maintenance/cleanup-sessions

Descripcion: Limpiar sesiones expiradas

GET /admin/system/cron/status

Descripcion: Estado de trabajos CRON

12. MONITORING ENDPOINTS

GET /admin/monitoring/metrics

Descripcion: Metricas actuales del sistema

GET /admin/monitoring/metrics/history

Descripcion: Historial de metricas

GET /admin/monitoring/errors/stats

Descripcion: Estadisticas de errores

GET /admin/monitoring/errors/recent

Descripcion: Errores recientes con detalles

GET /admin/monitoring/errors/trends

Descripcion: Tendencias de errores

13. ROLES & PERMISSIONS ENDPOINTS

GET /admin/roles

Descripcion: Obtener todos los roles

GET /admin/roles/permissions

Descripcion: Obtener permisos disponibles

GET /admin/roles/:id/permissions

Descripcion: Obtener permisos de rol

PUT /admin/roles/:id/permissions

Descripcion: Actualizar permisos de rol

14. REPORTS ENDPOINTS

POST /admin/reports/generate

Descripcion: Generar nuevo reporte

Body:

{
  "type": "users|progress|analytics|content",
  "format": "pdf|csv|xlsx",
  "filters": {...}
}

GET /admin/reports

Descripcion: Listar reportes

GET /admin/reports/:id/download

Descripcion: Descargar reporte

DELETE /admin/reports/:id

Descripcion: Eliminar reporte

15. CLASSROOM-TEACHER ENDPOINTS

POST /admin/classrooms/assign

Descripcion: Asignar aula a profesor

POST /admin/classrooms/bulk-assign

Descripcion: Asignacion masiva de aulas

DELETE /admin/classrooms/assign/:teacherId/:classroomId

Descripcion: Remover asignacion

POST /admin/classrooms/reassign

Descripcion: Reasignar aula a otro profesor

GET /admin/classrooms/teacher/:teacherId

Descripcion: Obtener aulas de profesor

GET /admin/classrooms/available

Descripcion: Obtener aulas disponibles

GET /admin/classrooms/:classroomId/history

Descripcion: Historial de asignaciones

GET /admin/classrooms/:id/teachers

Descripcion: Obtener profesores de aula

POST /admin/classrooms/:id/teachers

Descripcion: Asignar profesor a aula

DELETE /admin/classrooms/:id/teachers/:tid

Descripcion: Remover profesor de aula

GET /admin/teachers/:id/classrooms

Descripcion: Obtener aulas de profesor

POST /admin/teachers/:id/classrooms

Descripcion: Asignar aulas a profesor

GET /admin/classroom-teachers

Descripcion: Listar todas las asignaciones

POST /admin/classroom-teachers/bulk

Descripcion: Asignacion masiva de pares

GET /admin/classrooms/list

Descripcion: Listar aulas para dropdowns

GET /admin/teachers/list

Descripcion: Listar profesores para dropdowns

16. FEATURE FLAGS ENDPOINTS

GET /admin/feature-flags

Descripcion: Obtener todos los feature flags

GET /admin/feature-flags/:key

Descripcion: Obtener flag por key

POST /admin/feature-flags/:key/check

Descripcion: Verificar si feature esta habilitada

POST /admin/feature-flags

Descripcion: Crear nuevo flag

PUT /admin/feature-flags/:key

Descripcion: Actualizar flag

POST /admin/feature-flags/:key/enable

Descripcion: Habilitar flag

POST /admin/feature-flags/:key/disable

Descripcion: Deshabilitar flag

PUT /admin/feature-flags/:key/rollout

Descripcion: Actualizar rollout percentage

DELETE /admin/feature-flags/:key

Descripcion: Eliminar flag

17. ASSIGNMENTS ENDPOINTS

GET /admin/assignments

Descripcion: Listar asignaciones con filtros

GET /admin/assignments/stats

Descripcion: Estadisticas globales

GET /admin/assignments/:id

Descripcion: Detalle de asignacion

GET /admin/assignments/classrooms/:classroomId

Descripcion: Asignaciones de aula

GET /admin/assignments/students/:studentId

Descripcion: Asignaciones de estudiante

AUTENTICACION Y AUTORIZACION

Todos los endpoints requieren:

  • Header: Authorization: Bearer <jwt_token>
  • Rol requerido: super_admin

CODIGOS DE RESPUESTA

Codigo Descripcion
200 Exito
201 Creado
400 Solicitud invalida
401 No autenticado
403 No autorizado (requiere super_admin)
404 No encontrado
409 Conflicto (operacion en progreso)
500 Error del servidor

SERVICES DEL MODULO

  1. AdminAlertsService
  2. AdminAnalyticsService
  3. AdminAssignmentsService
  4. AdminContentService
  5. AdminDashboardService
  6. AdminInterventionsService
  7. AdminMonitoringService
  8. AdminOrganizationsService
  9. AdminProgressService
  10. AdminReportsService
  11. AdminRolesService
  12. AdminSystemService
  13. AdminUsersService
  14. BulkOperationsService
  15. ClassroomAssignmentsService
  16. FeatureFlagsService
  17. GamificationConfigService
  18. DashboardStatsService
  19. UserStatsService
  20. ContentStatsService
  21. RecentActivityService
  22. AdminQueryBuilder

ENTIDADES

  1. SystemSetting - Configuraciones del sistema
  2. FeatureFlag - Feature flags globales
  3. NotificationSettings - Config de notificaciones
  4. BulkOperation - Registro de operaciones masivas
  5. SystemAlert - Alertas del sistema
  6. AdminReport - Reportes generados

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