Saltar a contenido

0018. Listados sin borrados por defecto y filtro ?estado=

Estado: Aceptado Fecha: 2026-10-07 Autor: David Garcia Módulo(s) afectado(s): app/shared/schemas.py, app/domains/catalogos/ Modifica a: ADR 0015

Contexto

El ADR 0015 hizo que el listado de un catálogo devolviera también los borrados. Así, quien consume la API (un selector del frontend, por ejemplo) recibe registros que ya no debe ofrecer, y tiene que descartar los de is_activo = false por su cuenta.

Decisión

  • El listado acepta ?estado=activos|borrados|todos, con activos por defecto. Un valor distinto responde 422.
  • "Borrado" significa deleted_at con valor, la misma condición que usa el borrado lógico.
  • GET /{id} no cambia: devuelve el registro aunque esté borrado (con is_activo = false), para poder resolver referencias de datos antiguos. PUT y DELETE tampoco cambian.
  • El enum EstadoRegistro va en app/shared/schemas.py, para que lo usen los listados de los demás dominios.

Alternativas descartadas

  • Booleano incluir_borrados — no permite pedir sólo los borrados (por ejemplo, para una pantalla de restauración).
  • Excluir siempre los borrados — no habría forma de listarlos por la API.
  • 404 en GET /{id} de un borrado — un pedido antiguo que apunta a un método de pago borrado no podría mostrarlo.

Consecuencias

  • Cambio de contrato: un cliente que leía los borrados en el listado debe pedir ?estado=todos.
  • El código sigue siendo único aunque el registro esté borrado: crear un código que no aparece en el listado por defecto puede responder 409.

Media página como máximo. Si el ADR crece más que eso, probablemente estás documentando el diseño completo del módulo, no una decisión puntual — separa.