0053. Escrituras de los catálogos globales exclusivas de root¶
Estado: Aceptado Fecha: 2026-10-26 Autor: David Garcia Módulo(s) afectado(s): app/domains/catalogos/, app/main.py, docs/adr/
Contexto¶
Durante la revisión del ADR 0052 se constató que las escrituras de los
catálogos globales (países, tipos de identificación, géneros, monedas,
provincias y ciudades) no exigían el token administrativo root: aceptaban un
token normal válido con get_current_user. La frase del ADR 0048 «las
escrituras de catálogos [...] permanecen protegidos por la autenticación
normal» se implementó literalmente, pero ese nivel es insuficiente: cualquier
usuario de cualquier empresa de la plataforma podía crear, modificar o borrar
lógicamente datos de referencia globales que consumen todos los servicios,
por ejemplo códigos de países o de tipos de identificación validados por otros
microservicios.
La superficie administrativa tiene un principio opuesto: la edición del universo global es solo de root, como en el CRUD de empresas.
Decisión¶
- Las escrituras de los catálogos globales (
POST/PUT/DELETEde países, tipos de identificación, géneros, monedas, provincias y ciudades) exigen el token administrativo root medianteUsuarioAdminAutenticado(get_admin_user, ADR 0048):403 «Acceso no autorizado»ante un token normal y401sin token o inválido. Revierte al criterio root-only y corrige la apertura que la lectura literal del ADR 0048 permitió: este ADR sustituye esa frase del 0048 en el punto específico de las escrituras de catálogos. - Sesión pelada para las escrituras globales: los endpoints viven en un
sub-router propio fuera de la superficie protegida por el token normal (el
router_protegidodeapp/main.pyexigeget_current_user, incompatible con el token administrativo, que no traeempresa_id). El service se arma conget_db, sin contexto de RLS: son catálogos globales sin alcance tenant, igual que el CRUD de empresas. - En la matriz y en el código queda marcado el 0052: el listado de las listas maestras sigue abierto a cualquier usuario autenticado (0052) y este ADR no modifica ninguna lectura.
- Feriados y bancos no cambian: son catálogos por empresa (ámbito
tenant). Siguen con autenticación normal y sesión de RLS, como ya decía el
ADR 0048 para los endpoints de catálogos con ámbito tenant. Con un token
administrativo responden
401, porque elrouter_protegidoexige el token normal.
Códigos de respuesta¶
| Petición | Token normal | Token admin/root | Sin token o inválido |
|---|---|---|---|
GET listado de catálogos globales (incluye existe/{id}) |
200 | 200 | 401 |
GET /catalogos/{recurso}/{id} (detalle) |
200 | 401 | 401 |
POST/PUT/DELETE de países, tipos de identificación, géneros, monedas, provincias y ciudades |
403 | 201/200/204 | 401 |
POST/PUT/DELETE de feriados y bancos (por empresa) |
igual que antes | 401 | 401 |
La fila del detalle no varía respecto del estado previo: vivía (y vive) bajo la superficie normal, y el token administrativo no la atraviesa.
Alternativas descartadas¶
- Dejar las escrituras con autenticación normal — es el estado hallado. Da edición global de datos de referencia a cualquier usuario autenticado y contradice el principio de la superficie administrativa (0048).
- Cambiar la dependencia del
router_protegido— protegería las escrituras, pero rompería los demás dominios (navegación, sucursales, usuarios) que requieren explícitamente el token normal. - Abrir también el detalle por id al token administrativo — unificar la superficie de lectura de la ficha completa es otra decisión (la de sucursales del 0052 fue dejada abierta); acá el detalle no cambia.
Consecuencias¶
- Código: los 18 endpoints de escritura global se reagrupan en
catalogos_escritura_routeryapp/main.pylos monta fuera de la superficie normal. Las firmas agreganUsuarioAdminAutenticadoy el service pasa aget_db. Sin cambios de contrato: códigos409y404de negocio se conservan. - El token normal queda en solo lectura para los seis catálogos: afecta a cualquier integración que hoy escriba catálogos con token normal.
- Pruebas unitarias (service falso y tokens JWT reales): listado con
token normal
200y sin token401;POST/PUT/DELETEcon token normal403 «Acceso no autorizado»; con token administrativo, la escritura responde201; elPOSTde feriados con token normal sigue201. - Los otros servicios mantienen su lectura autenticada (0052): nada cambia para quien consume las listas; solo para quien las edita.