Saltar a contenido

0013. CRUD de los catálogos globales — sexto slice: provincias

Estado: Aceptado Fecha: 2026-09-29 Autor: Duval Alcivar Módulo(s) afectado(s): app/domains/catalogos/, tests/unit/catalogos/

Contexto

Los ADR 0008–0012 establecieron el patrón CRUD de los catálogos globales (países, tipos de identificación, géneros, monedas) y la fusión de tipos de documentos. Este ADR lo replica para cat_provincias, el primer catálogo con clave foránea: pais_id referencia a cat_paises.id.

Decisión

  • POST /api/v1/catalogos/provincias (201): crea una provincia.
  • PUT /api/v1/catalogos/provincias/{provincia_id} (200): actualización parcial.
  • DELETE /api/v1/catalogos/provincias/{provincia_id} (204): borrado lógico.

El repository hace add/commit/refresh y las lecturas filtran deleted_at IS NULL. Sin campo único en el modelo, no hay validación de duplicados ni respuestas 409 en este recurso.

Validación de FK: si el pais_id no existe (o está borrado), el service responde 404 con el detalle «País no encontrado». Se introduce la excepción PaisNoEncontradoError en el service, capturada por el router y traducida a HTTPException(404).

Alternativas descartadas

  • Esperar a la administración autenticada — los catálogos globales ya escriben sin auth desde el ADR 0008; replicar el patrón mantiene la consistencia del slice.
  • Borrado físico — contradice el borrado lógico de AuditMixin usado por todos los catálogos previos.
  • Devolver 422 en lugar de 404 para la FK inexistente — se prefirió 404, consistente con el lenguaje del repositorio: «País no encontrado» expresa que la referencia no existe, igual que los 404 de recursos inexistentes.

Consecuencias

  • Supera parcialmente al ADR 0006, que dejaba a cat_provincias en solo lectura.
  • Introduce el patrón de validación de FK que cat_ciudades (y luego feriados y bancos) reutilizarán cuando tengan su slice de escritura.
  • OpenAPI suma 3 endpoints (pasa a 31).