Saltar a contenido

0008. CRUD de los catálogos globales — primer slice: países

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

Contexto

El ADR 0006 dejó los catálogos en solo lectura a la espera de la administración autenticada. Los catálogos globales no llevan empresa_id ni RLS, así que se puede adelantar su CRUD sin autenticación como decisión consciente. Este ADR es el primer slice: países.

Decisión

  • POST /api/v1/catalogos/paises — crea un país y responde 201 con el recurso creado.
  • PUT /api/v1/catalogos/paises/{pais_id} — actualización parcial con campos opcionales; responde 200.
  • DELETE /api/v1/catalogos/paises/{pais_id} — borrado lógico; responde 204.
  • El repository hace add/commit/refresh; el commit no vive en el router ni en el service.
  • La unicidad del codigo se valida en el service y ante duplicado responde 409.
  • Las lecturas (listar_paises, obtener_pais) filtran deleted_at IS NULL.
  • created_by/updated_by quedan NULL hasta que exista autenticación.

Alternativas descartadas

  • Esperar la administración autenticada — los catálogos globales son públicos y sin RLS; bloquear su escritura no aporta seguridad.
  • Borrado físico — el resto del modelo usa borrado lógico (deleted_at); un DELETE físico rompería la auditoría y las referencias.
  • PATCH separado de PUT — la actualización parcial con PUT y campos opcionales cubre el caso sin sumar un verbo más.

Consecuencias

  • Supera parcialmente al ADR 0006: la escritura queda habilitada solo para los catálogos globales.
  • Feriados y bancos (por empresa) siguen esperando autenticación: llevan empresa_id y RLS.
  • Los demás catálogos globales replicarán este patrón en slices siguientes.
  • OpenAPI expone 3 endpoints nuevos.