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
AuditMixinusado 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 los404de recursos inexistentes.
Consecuencias¶
- Supera parcialmente al ADR 0006, que dejaba a
cat_provinciasen 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).