0014. CRUD de los catálogos globales — séptimo slice: ciudades¶
Estado: Aceptado Fecha: 2026-09-29 Autor: Duval Alcivar Módulo(s) afectado(s): app/domains/catalogos/, tests/unit/catalogos/
Contexto¶
El ADR 0013 estableció el patrón CRUD con clave foránea para cat_provincias.
Este ADR lo replica para cat_ciudades, el segundo catálogo con clave foránea:
provincia_id referencia a cat_provincias.id.
Decisión¶
POST /api/v1/catalogos/ciudades(201): crea una ciudad.PUT /api/v1/catalogos/ciudades/{ciudad_id}(200): actualización parcial.DELETE /api/v1/catalogos/ciudades/{ciudad_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 provincia_id no existe (o está borrado), el service
responde 404 con el detalle «Provincia no encontrada». Se introduce la
excepción ProvinciaNoEncontradoError 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: «Provincia no encontrada» expresa que la referencia no existe, igual que los404de recursos inexistentes.
Consecuencias¶
- Supera parcialmente al ADR 0006, que dejaba a
cat_ciudadesen solo lectura. - Completa los catálogos globales con clave foránea: provincias (ADR 0013) y ciudades quedan con el mismo patrón de validación de FK.
- OpenAPI suma 3 endpoints (pasa a 34).