Saltar a contenido

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 por id para 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: router valida y delega, service coordina sin SQL y repository es el único que toca SQLAlchemy. El router arma el service con su repository sobre la sesión del request (get_db).
  • El router traduce None en HTTP 404; la respuesta usa los schemas Read del 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 curl a /api/v1/catalogos/paises responde 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.