Saltar a contenido

0052. Lectura autenticada de las listas maestras

Estado: Aceptado Fecha: 2026-10-26 Autor: David Garcia Módulo(s) afectado(s): app/api/deps.py, app/domains/catalogos/, app/domains/empresas/, app/domains/sucursales/, docs/adr/

Contexto

La aplicación React necesita las listas maestras para llenar combos y validar referencias: catálogos globales, empresas y sucursales. Después del ADR 0048, los listados de empresas y sucursales exigían token administrativo root, y de los catálogos globales sólo cuatro listados (países, provincias, ciudades y tipos de identificación) usaban la dependencia de lectura reutilizable: los de géneros y monedas vivían en el router protegido por la autenticación normal, sin el token administrativo.

Un usuario normal autenticado necesita leer esas listas para operar la aplicación; exigirle el token administrativo (o restringirle media plataforma) es una fricción sin beneficio de seguridad para lecturas de datos de referencia.

Decisión

  • El GET de listado (ruta sin id) de los catálogos globales, de empresas y de sucursales queda abierto a cualquier usuario autenticado: basta un token válido del flujo normal (React). El token administrativo root también se acepta, porque root consulta las mismas listas desde el panel Vue.
  • La dependencia existe y se reutiliza: get_catalog_read_user, que ya defendía las cuatro listas globales del ADR 0048, pasa a cubrir géneros, monedas y los dos listados nuevos, con el alias UsuarioLecturaListas. Los catálogos globales usan la superficie de lectura con sesión pelada, sin contexto de empresa (son datos de referencia sin RLS).
  • El detalle por id y las acciones de escritura no cambian: el CRUD de empresas y sucursales sigue root-only (ADR 0048); el detalle y las escrituras de catálogos conservan la protección que ya tenían. Este ADR no abre ninguna escritura. Nota posterior: la revisión halló que las escrituras globales de catálogos no exigían el token administrativo root, y esa discrepancia quedó resuelta por el ADR 0053.
  • Sin rutas gemelas: no se duplican endpoints con un sufijo público ni se agrega un grupo nuevo de consumo; sólo cambia la dependencia del listado.

Códigos de respuesta del listado

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 /api/v1/empresas 200 200 401
GET /api/v1/sucursales 200 401 401
Detalle por id y POST/PUT/DELETE de los tres dominios igual que antes (ADR 0048) igual que antes 401

La fila de sucursales refleja la topología vigente: ese router vive bajo la superficie protegida normal (router_protegido, ADR 0031), que rechaza el token administrativo antes de llegar al endpoint. Unificar ambas superficies para el token administrativo se decide aparte.

Alternativas descartadas

  • Abrir también el detalle por id — la ficha completa de una empresa o sucursal no es un dato de referencia: expone más de lo que un combo necesita.
  • Abrir el CRUD a cualquier usuario autenticado — contradice el ADR 0048 y da escritura global a cualquier usuario.
  • Filtrar por permisos del claim permisos desde ya — los claims existen, pero la granularidad por permiso es una decisión abierta y aún no se realiza (ver más abajo).

Consecuencias

  • Código: ninguna entrada nueva de API. listar_generos y listar_monedas se suman a la superficie de lectura global de catálogos, y los listados de empresas y sucursales cambian de la dependencia administrativa a la de lectura. Todo lo demás queda igual.
  • Las listas sin id son públicas para usuarios autenticados, incluidas todas las empresas y sucursales de la plataforma (el listado de sucursales corre con sesión pelada, sin RLS, por diseño de este CRUD).
  • existe/{id} de tipos de identificación y ciudades ya compartía esa superficie de lectura: no cambia, y los endpoints de entidades (ADR 0050 y 0051) siguen en el router protegido normal, sin cambios.
  • Pruebas unitarias (services falsos con dependency_overrides, sin base real): listado sin token responde 401, con token normal responde 200 y el POST de empresas y sucursales con token normal responde 403 con el detalle «Acceso no autorizado»; el detalle por id sigue protegido.

Qué no cubre / decisión abierta

  • Autorización granular por permisos para estas lecturas (por ejemplo, restringir por rol o por permisos del claim): queda abierta como decisión futura, todavía no se realiza. Cuando se implemente, deberá encabezar un ADR propio.
  • Las superficies del token administrativo y la sesión pelada del listado de sucursales no se tocan en este ADR.