Saltar a contenido

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 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: «Provincia no encontrada» expresa que la referencia no existe, igual que los 404 de recursos inexistentes.

Consecuencias

  • Supera parcialmente al ADR 0006, que dejaba a cat_ciudades en 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).