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
CatalogoRepositoryqueda redundante pero inofensivo. - Ningún modelo sin
deleted_at(por ejemplolog_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_optionso una consulta cruda; queda documentado como trabajo futuro.