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
empresasy desucursalesqueda 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 aliasUsuarioLecturaListas. 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
permisosdesde 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_generosylistar_monedasse suman a la superficie de lectura global de catálogos, y los listados deempresasysucursalescambian 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 elPOSTde 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.