fix: [TESIS-155] bound the page number of every listing

[LauAubert]

Ticket de Jira

https://proyectofinalfrlp.atlassian.net/browse/TESIS-155

ID provisorio: se reemplaza por la clave real al cargar la card en Jira. Card: cards/022.md. Sale de una auditoría de código (TESIS-89).

---

Descripción

Api::V1::Paginatable#page_number acotaba la página sólo por abajo ([page.to_i, 1].max). Con un ?page= de veinte dígitos, el OFFSET desbordaba bigint, Postgres levantaba NumericValueOutOfRange (ActiveRecord::RangeError) y cualquier listado de la API respondía 500: órdenes, productos, envíos, transferencias, depósitos, eventos fallidos.

• Agrega Paginatable::MAX_PAGE = 1_000_000 y acota la página con clamp(1, MAX_PAGE). Un millón de páginas de cien filas está muy por encima de cualquier listado real y muy lejos del límite de la base.
• Una página así se lee como la última aceptada y responde vacía, con el total real: el mismo criterio que ya tenía una página pasada del final, y el mismo criterio «acotar en vez de romper» que el concern aplica a page=0 y a per_page.
• Spec: ?page=99999999999999999999 responde 200 con data vacío y meta.page == MAX_PAGE.

---

Evidencia visual

N/A

---

Cómo probar

1. GET /api/v1/orders?page=99999999999999999999 → 200 {"data": [], "meta": {"page": 1000000, "per_page": 20, "total": N}}. En master, 500.
2. GET /api/v1/orders?page=2 → igual que antes.

Verificación: bundle exec rspec (1568 ejemplos, 0 fallas, cobertura 99.89% de línea), rubocop y brakeman limpios.

Dientes: con el page_number de master, el spec nuevo falla con ActiveRecord::RangeError.

---

Impacto y consideraciones

¿Introduce breaking changes?
No

¿Requiere nuevas variables de entorno?
No

¿Afecta la arquitectura o genera un nuevo patrón?
No

🤖 Generated with Claude Code

[TomasMartin2004]

Revisado. Lo veo bien para implementar.

20 líneas que sacan un 500 de todos los listados de la API —órdenes, productos, envíos, transferencias, depósitos, eventos fallidos— con sólo mandar un ?page= largo: el OFFSET desbordaba bigint y Postgres levantaba NumericValueOutOfRange. Es el tipo de hallazgo que corresponde a la tarea de QA de seguridad del entorno desplegado, y ahora que el sistema está sirviendo en la VPS vale más que cuando se escribió.

Lo que verifiqué

• clamp(1, MAX_PAGE) mantiene el criterio que el método ya tenía por abajo (page=0 y page=-3 se acotan en vez de dar 400) y lo aplica por arriba con la misma lógica. Coherente con lo que ya estaba escrito y comentado.
• MAX_PAGE = 1_000_000 por MAX_PER_PAGE = 100 da un offset máximo de 100.000.000: muy por debajo del límite de bigint. Holgado.
• El spec verifica las tres cosas que importan: 200, data vacía y meta.page acotado. Que meta devuelva MAX_PAGE y no el número pedido está bien y está comentado.

Sin objeciones. scan_ruby en rojo es la corrida vieja del 02/10, no el cambio.

[TomasMartin2004]

Revisión del diff completo. El código es idéntico al que leí cuando los PRs estaban en draft —ningún commit nuevo—, así que lo que sigue es el veredicto formal.

✅ Aprobado

20 líneas que sacan un 500 de todos los listados de la API —órdenes, productos, envíos, transferencias, depósitos, eventos fallidos— con sólo mandar un ?page= largo: el OFFSET desbordaba bigint y Postgres levantaba NumericValueOutOfRange. Ahora que el sistema está sirviendo en la VPS vale más que cuando se escribió.

Lo que verifiqué

• clamp(1, MAX_PAGE) mantiene el criterio que el método ya tenía por abajo (page=0 y page=-3 se acotan en vez de dar 400) y lo aplica por arriba con la misma lógica.
• MAX_PAGE = 1_000_000 por MAX_PER_PAGE = 100 da un offset máximo de 100.000.000, muy por debajo del límite de bigint.
• El spec verifica las tres cosas que importan: 200, data vacía y meta.page acotado. Que meta devuelva MAX_PAGE y no el número pedido está bien y está comentado.

Sin objeciones.