Saltar a contenido

0008. CRUD de los catálogos — primer slice: canales comerciales

Estado: Propuesto Fecha: 2026-09-29 Autor: Kevin Delgado Lopez Módulo(s) afectado(s): app/domains/catalogos/, tests/unit/catalogos/

Contexto

Los 8 catálogos comerciales tienen modelo, migración y RLS (ADR 0003 y 0004), pero ningún endpoint. Hace falta un molde de CRUD que después se repita, tabla por tabla, en los demás catálogos y dominios. Este ADR es el primer slice: cat_canales_comerciales.

Decisión

  • Endpoints bajo /api/v1/catalogos/canales-comerciales: GET lista, GET /{id}, POST (201; 409 si el código existe), PUT /{id} (nombre y descripción) y DELETE /{id} (204, borrado lógico).
  • Un CatalogoRepository y un CatalogoService por dominio, con una sección por tabla y métodos explícitos (listar_, obtener_, existe_codigo_, crear_, actualizar_, eliminar_<x>). Sin métodos genéricos, clase base ni helpers.
  • Cada escritura del repository hace su commit, con flush + refresh antes (ADR 0006: la empresa es local a la transacción).
  • El service se arma en router.py (get_catalogo_service): sesión con empresa → repository → service, como core-svc-identidad.
  • Borrado lógico: deleted_at e is_activo = false; es idempotente. Los listados y el GET /{id} devuelven también los borrados; el 404 es sólo para un id que no existe.
  • El código es único por empresa aunque el registro esté borrado, igual que el UNIQUE de la base.

Alternativas descartadas

  • Repository genérico o RepositorioBase — si una tabla necesita una consulta distinta, el genérico se rompe para todas.
  • Filtrar deleted_at IS NULL en las lecturas — el frontend no podría ver ni reactivar lo borrado; filtra por is_activo si quiere.
  • commit en el service — el service quedaría atado a la sesión de SQLAlchemy.
  • dependencies.py por dominio — no está en la estructura de la plataforma.
  • Los 8 catálogos de una vez — se agregan de a uno para revisar cada slice.

Consecuencias

  • Los demás catálogos repiten este molde; cada uno suma su ADR de slice.
  • Las pruebas usan una subclase en memoria del repository, sin base de datos.

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.