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 resuelvehasta, 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
iddescendente y descarta lo que queda fuera del rango. Si los historiales crecen mucho y los rangos se vuelven lentos, se puede sumar un índice concreated_ato acotar también porid, 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.