Saltar a contenido

0015. Scope global de borrado lógico: filtro automático de deleted_at

Estado: Aceptado Fecha: 2026-09-29 Autor: Duval Alcivar Módulo(s) afectado(s): app/core/db.py, tests/unit/core/

Contexto

Desde los slices ADR 0008–0014, cada repository filtra a mano deleted_at.is_(None) en sus lecturas. El filtro es fácil de olvidar en una consulta nueva y no cubre caminos como Session.get(), que no pasa por un where explícito del repository. El dueño pidió el equivalente del scope global SoftDeletes de Laravel: que el ORM filtre las filas borradas por defecto, sin depender de que cada repository lo recuerde.

Decisión

Se registra un listener do_orm_execute en app/core/db.py sobre la clase Session síncrona de sqlalchemy.orm —los eventos ORM no tienen versión async; AsyncSession envuelve una sesión síncrona y los eventos funcionan igual—. El handler inyecta with_loader_criteria(..., deleted_at.is_(None), include_aliases=True) para todo mapper con columna deleted_at (los que heredan AuditMixin), en todo SELECT de entidad: no en cargas de columna ni de relación.

El scope cubre también Session.get() y los relationship loads descendentes, porque with_loader_criteria se propaga automáticamente y ambos caminos emiten SELECT que pasan por do_orm_execute. Los filtros explícitos deleted_at.is_(None) que ya existen en CatalogoRepository se conservan como red de seguridad: son redundantes pero inofensivos, y la redundancia se acepta a propósito.

Alternativas descartadas

  • Filtrar solo en el repository (opción A) — explícito, pero repetitivo y fácil de olvidar en consultas nuevas; no cubre Session.get().
  • Un mixin de consulta base — no cubre Session.get() ni los relationship loads, que no pasan por el método del repository.
  • Un event listener por modelo — ruidoso: registra un handler por cada tabla y no se propaga a los mappers que se agreguen después.

Consecuencias

  • Todo SELECT del servicio filtra los borrados automáticamente; las consultas nuevas no necesitan recordarlo.
  • El filtro explícito en CatalogoRepository queda redundante pero inofensivo.
  • Ningún modelo sin deleted_at (por ejemplo log_sesiones, trx_pre_tokens) se ve afectado.
  • Si algún día se necesita ver filas borradas (auditoría, restore), habrá que saltarse el scope explícitamente con execution_options o una consulta cruda; queda documentado como trabajo futuro.