workspace/projects/gamilit/orchestration/reportes/ANALISIS-PAGINACION-MONITORING-2025-12-18.md

ANALISIS: Implementacion de Paginacion Completa - Teacher Monitoring

Fecha: 2025-12-18 Analista: Requirements-Analyst Proyecto: Gamilit Componente: Teacher Portal - Student Monitoring Panel

---

OBJETIVO

Implementar un sistema de paginacion completo en el frontend que permita:

1. Al usuario seleccionar cuantos registros mostrar por pagina (10, 25, 50, 100)
2. Navegar entre paginas (anterior, siguiente, ir a pagina especifica)
3. Que la paginacion se ejecute desde la base de datos (server-side)
4. Escalar correctamente para 100, 1000 o mas usuarios

---

ESTADO ACTUAL

Hook useStudentMonitoring

Archivo: apps/frontend/src/apps/teacher/hooks/useStudentMonitoring.ts

Estado actual:

• Hace una sola llamada a la API con limit: 100
• NO retorna informacion de paginacion (total, totalPages, etc.)
• NO tiene funciones para cambiar de pagina

const query: GetClassroomStudentsQueryDto = {
  limit: 100, // Hardcoded
};
const response = await classroomsApi.getClassroomStudents(classroomId, query);
setStudents(response.data || []);

Componente StudentMonitoringPanel

Archivo: apps/frontend/src/apps/teacher/components/monitoring/StudentMonitoringPanel.tsx

Estado actual:

• Muestra TODOS los estudiantes en una sola vista (cards o tabla)
• NO tiene controles de paginacion
• NO tiene selector de limite por pagina
• El filtrado y ordenamiento se hace en memoria (client-side)

Backend getClassroomStudents

Archivo: apps/backend/src/modules/teacher/services/teacher-classrooms-crud.service.ts

Estado actual:

• YA soporta paginacion server-side
• Recibe page y limit en query params
• Retorna PaginatedStudentsResponseDto con:
  • data: Array de estudiantes
  • pagination: { page, limit, total, totalPages, hasNextPage, hasPreviousPage }

---

COMPONENTES DE REFERENCIA EXISTENTES

Pagination en ResponsesTable.tsx

Archivo: apps/frontend/src/apps/teacher/components/responses/ResponsesTable.tsx:276-342

Componente de paginacion existente que incluye:

• Texto "Mostrando X - Y de Z resultados"
• Botones anterior/siguiente con iconos ChevronLeft/ChevronRight
• Numeros de pagina clickeables
• Estados deshabilitados para primera/ultima pagina

Props del componente:

interface PaginationProps {
  page: number;
  total: number;
  limit: number;
  onPageChange: (page: number) => void;
}

---

REQUERIMIENTOS FUNCIONALES

RF-001: Selector de Limite por Pagina

• El usuario debe poder seleccionar: 10, 25, 50, 100 registros por pagina
• Valor por defecto: 25
• Al cambiar el limite, volver a pagina 1

RF-002: Navegacion de Paginas

• Mostrar pagina actual y total de paginas
• Botones anterior/siguiente
• Input numerico para ir a pagina especifica (opcional)
• Deshabilitar botones en limites

RF-003: Informacion de Paginacion

• Mostrar: "Mostrando X - Y de Z estudiantes"
• Mostrar total de paginas disponibles

RF-004: Paginacion Server-Side

• Cada cambio de pagina hace una nueva llamada a la API
• La BD filtra y ordena antes de paginar
• Mantener filtros de busqueda/status al cambiar pagina

RF-005: Estados de Carga

• Mostrar spinner al cargar nueva pagina
• Mantener datos anteriores mientras carga (opcional)

---

ARQUITECTURA DE LA SOLUCION

[Usuario]
    |
    | Selecciona limit (25), clickea pagina 2
    v
[StudentMonitoringPanel]
    |
    | setPage(2), setLimit(25)
    v
[useStudentMonitoring hook]
    |
    | query = { page: 2, limit: 25, status: 'active' }
    v
[classroomsApi.getClassroomStudents]
    |
    | GET /api/v1/teacher/classrooms/:id/students?page=2&limit=25
    v
[Backend: TeacherClassroomsCrudService]
    |
    | OFFSET 25, LIMIT 25 en PostgreSQL
    v
[Base de Datos]
    |
    | Retorna registros 26-50 de 150 total
    v
[Response: { data: [...25 items], pagination: { page: 2, limit: 25, total: 150, totalPages: 6 }}]
    |
    v
[Frontend muestra 25 estudiantes de pagina 2]

---

COMPONENTES A MODIFICAR/CREAR

1. Componente StudentPagination (NUEVO)

Ruta propuesta: apps/frontend/src/apps/teacher/components/monitoring/StudentPagination.tsx

Componente reutilizable para paginacion con:

• Selector de limite (dropdown)
• Botones de navegacion
• Info de registros mostrados

2. Hook useStudentMonitoring (MODIFICAR)

Cambios:

• Agregar estados: page, limit, pagination
• Agregar funciones: setPage, setLimit
• Retornar info de paginacion

3. Componente StudentMonitoringPanel (MODIFICAR)

Cambios:

• Importar y usar StudentPagination
• Pasar props de paginacion al componente
• Actualizar stats con total real (no solo los de pagina actual)

4. Tipo PaginationInfo (VERIFICAR)

Ruta: apps/frontend/src/shared/types/api-responses.ts

Verificar que existe y tiene los campos necesarios.

---

FLUJO DE DATOS PROPUESTO

Estado inicial

// En useStudentMonitoring
const [page, setPage] = useState(1);
const [limit, setLimit] = useState(25);
const [pagination, setPagination] = useState<PaginationInfo | null>(null);

Llamada a la API

const query: GetClassroomStudentsQueryDto = {
  page,
  limit,
  status: filters?.status?.[0],
  sort_by: 'name',
  sort_order: 'asc',
};

const response = await classroomsApi.getClassroomStudents(classroomId, query);
setStudents(response.data || []);
setPagination(response.pagination);

Respuesta esperada

{
  data: StudentMonitoring[],
  pagination: {
    page: 2,
    limit: 25,
    total: 150,
    totalPages: 6,
    hasNextPage: true,
    hasPreviousPage: true
  }
}

---

CONSIDERACIONES DE UX

1. Mantener scroll position: Al cambiar pagina, scroll al inicio de la tabla
2. Loading state: Skeleton o spinner mientras carga
3. Persistencia: Guardar preferencia de limit en localStorage (opcional)
4. Responsive: Paginacion simplificada en mobile (solo prev/next)

---

DEPENDENCIAS IDENTIFICADAS

Componente	Dependencia	Estado
PaginationInfo type	shared/types/api-responses.ts	Verificar
GetClassroomStudentsQueryDto	services/api/teacher/classroomsApi.ts	YA ACTUALIZADO
Backend endpoint	teacher-classrooms-crud.service.ts	YA SOPORTA
DetectiveButton	shared/components/base	Disponible
DetectiveCard	shared/components/base	Disponible

---

SIGUIENTE FASE

FASE 3: Planeacion detallada de implementacion con orden de archivos a modificar.