Saltar a contenido

0031. Historial por rango de fechas

Estado: Aceptado Fecha: 2026-10-28 Autor: Kevin Delgado Módulo(s) afectado(s): app/shared/auditoria/, tests/unit/shared/

Contexto

GET /api/v1/auditoria (ADR 0030) devuelve el historial del más reciente al más antiguo, de a limite eventos, y sólo se pagina hacia atrás con antes_de. El frontend necesita filtrarlo por rango de fechas: "hoy", "los últimos 7 días", "octubre". Con lo que había, eso exigía pedir página tras página hasta pasar la fecha de inicio, o armar a mano un uuidv7 con la fecha de fin para usarlo de antes_de. Eso último depende de cómo se generan los ids, que no es parte del contrato.

Decisión

  • Dos parámetros opcionales en GET /api/v1/auditoria:
  • desde: incluido (created_at >= desde);
  • hasta: excluido (created_at < hasta).

Se combinan con referencia_id, antes_de, limite y la cartera igual que antes. Sin ellos la consulta no cambia. - Fecha y hora con zona horaria (ISO 8601, ej. 2026-10-28T00:00:00-05:00; tipo AwareDatetime de pydantic): - el cliente decide dónde empieza y termina su día (el de un usuario en Ecuador no es el día UTC); - sin zona es 422. - desde debe ser anterior a hasta: si no, 422 con {"detail": "desdedebe ser anterior ahasta"}, antes de consultar. - hasta excluido: "el 28 de octubre" es desde=28T00:00 y hasta=29T00:00, sin tener que calcular el último instante del día. - Se filtra por created_at, no por el id. Aunque el id es uuidv7, created_at es la fecha que se muestra y la que el usuario elige.

Alternativas descartadas

  • Fechas sin hora (date): el servicio tendría que suponer la zona horaria del usuario para saber dónde empieza el día.
  • Armar un uuidv7 en el frontend y usarlo de antes_de: sólo resuelve hasta, y ata al frontend a cómo se generan los ids.
  • Filtrar en el frontend lo que ya cargó: con un historial largo obliga a bajar todas las páginas del rango.

Consecuencias

  • Los índices de ADR 0030 siguen sirviendo: la consulta recorre por id descendente y descarta lo que queda fuera del rango. Si los historiales crecen mucho y los rangos se vuelven lentos, se puede sumar un índice con created_at o acotar también por id, sin cambiar el contrato.
  • El contrato suma dos parámetros opcionales: los clientes actuales no cambian.
  • Un filtro por usuario (actor_username) seguiría el mismo molde; queda fuera de esta decisión.