0006. Endpoints de lectura de los catálogos¶
Estado: Aceptado Fecha: 2026-09-28 Autor: Duval Alcivar Módulo(s) afectado(s): app/domains/catalogos/, app/main.py, tests/
Contexto¶
Los modelos (ADR 0004) y los contratos Pydantic (ADR 0005) ya existen. El
servicio necesita su primera API real para que el stack
router → service → repository → base de datos funcione de punta a punta. Los
catálogos son el slice ideal: globales, sin RLS y sin autenticación, así que se
pueden exponer sin esperar la capa de auth.
Decisión¶
- 18 endpoints de solo lectura bajo
/api/v1/catalogos/*: lista + detalle poridpara cada uno de los 9 catálogos (paises,tipos-identificacion,generos,monedas,tipos-documentos,provincias,ciudades,feriados,bancos). - Patrón de capas del ADR 0001 transversal, por primera vez materializado
en el servicio:
routervalida y delega,servicecoordina sin SQL yrepositoryes el único que toca SQLAlchemy. El router arma el service con su repository sobre la sesión del request (get_db). - El router traduce
Noneen HTTP 404; la respuesta usa los schemasReaddel ADR 0005 (response_model). - El router se monta en
create_app()(include_router).
Alternativas descartadas¶
- CRUD completo ahora — los catálogos los siembra el sistema; la escritura espera la administración autenticada.
- Exigir autenticación — los catálogos globales son públicos; meter auth hoy retrasaría el primer endpoint funcional sin aportar seguridad.
- Un factory de routers genérico para los 9 recursos — menos repetición, pero más indirección y peor trazabilidad; se prefirió el patrón explícito, que además es el que seguirán los maestros (con CRUD que no encaja en un factory de solo lectura).
Consecuencias¶
- OpenAPI documenta 18 endpoints; un
curla/api/v1/catalogos/paisesresponde ya (con la base levantada y el seed). - El patrón router → service → repository queda establecido para el resto de dominios; los maestros replicarán la forma con CRUD y auth.
- Repetición deliberada en las capas: es el precio del patrón explícito; si un bloque de catálogos crece mucho, se puede extraer un factory después.