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
codigose valida en el service y ante duplicado responde 409. - Las lecturas (
listar_paises,obtener_pais) filtrandeleted_at IS NULL. created_by/updated_byquedan 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); unDELETEfí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_idy RLS. - Los demás catálogos globales replicarán este patrón en slices siguientes.
- OpenAPI expone 3 endpoints nuevos.