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:GETlista,GET /{id},POST(201; 409 si el código existe),PUT /{id}(nombre y descripción) yDELETE /{id}(204, borrado lógico). - Un
CatalogoRepositoryy unCatalogoServicepor 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, conflush+refreshantes (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_ateis_activo = false; es idempotente. Los listados y elGET /{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 NULLen las lecturas — el frontend no podría ver ni reactivar lo borrado; filtra poris_activosi quiere. commiten el service — el service quedaría atado a la sesión de SQLAlchemy.dependencies.pypor 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.