Saltar al contenido principal

TEC-003 — Paginación con Cursor

· 2 min de lectura
Yovany Suárez Silva
Software Engineer - FullStack Developer

Implementación de la mejora TEC-003 (Paginación con Cursor), dentro de 6.1 Rendimiento y Escalabilidad. Los listados de gran volumen dejan de saltar por OFFSET y pasan a pedir «a partir de esta fila», con un cursor opaco y resultados consistentes.


📋 Alcance​

RFEntregable
RF-TEC-003-01Paginación con cursor en endpoints de grandes volúmenes
RF-TEC-003-02Consistencia de resultados (orden estable con desempate por PK)
RF-TEC-003-03Cursor de la siguiente página en la respuesta (meta.nextCursor)
RF-TEC-003-04Migración progresiva: modo=cursor sin romper el offset

⚙️ Cómo funciona​

  • Contrato: PaginacionCursorDto añade modo (offset por defecto), cursor y order. La respuesta es CursorPage<T>: { data, meta: { limit, nextCursor, hasNextPage, order, orderBy } }.
  • Keyset: se ordena por el campo de fecha y la clave primaria como desempate, y el predicado es (fecha, id) < (:fecha, :id). Insertar o borrar filas no desplaza la ventana: no hay repetidos ni saltos.
  • Cursor opaco: base64url de un JSON con la última fila. Se piden limit + 1 filas para saber si hay página siguiente sin un COUNT(*).
  • Migración progresiva: el offset sigue siendo el comportamiento por defecto; se pide el cursor con ?modo=cursor. Ningún cliente actual se rompe.

🔌 Endpoints migrados​

EndpointOrden keyset
GET /api/movimientos-inventariofechaMovimiento, idMovimiento desc
GET /api/logs-operacionfechaHora, idLog desc
GET /api/loggerscreatedAt, loggerId desc
GET /api/notificationscreado, notificacionId desc
GET /api/productosidProducto asc
GET /api/solicitudesidSolicitud desc

Los demás listados (devoluciones, conteos, almacenes, oficinas, etc.) quedan documentados para migrar después con el mismo helper (aplicarKeyset / aplicarKeysetPorId).

🖥️ Frontend​

  • Movimientos de inventario: la carga inicial usa cursor (100) y un botón «Cargar más» añade la siguiente página, en lugar de traer 500 y paginar en cliente.
  • Auditoría: lista incremental por cursor con «Cargar más» y búsqueda filtrada en cliente.

✅ Verificación​

  • 545 pruebas en 55 suites, 0 fallos en la API; 45 pruebas en 11 suites, 0 fallos en el frontend. tsc y ESLint limpios en lo añadido.
  • Pruebas nuevas del helper (codificar/decodificar/construir página/predicados) y de findAllCursor en dos servicios representativos (logs de operación y notificaciones).

Nota: solicitudes.service.ts y app.module.ts arrastran deuda de lint de otras sesiones (codigosAdvertencia sin usar, imports de entidades tras el refactor a ENTIDADES_APP); no se tocaron.