0036. Panel de navegación por usuario (aplicaciones, módulos y menú)¶
Estado: Aceptado Fecha: 2026-10-02 Autor: Duval Alcivar Módulo(s) afectado(s): app/domains/dashboard/, app/main.py, tests/unit/dashboard/, docs/adr/
Contexto¶
El frontend necesita pintar el panel del usuario: qué aplicaciones y módulos ve, y qué entradas de menú y acciones puede usar. Esas piezas ya existen —las administran los slices de navegación (ADR 0020 a 0023), de aplicaciones de la empresa (ADR 0033) y de permisos por acción (ADR 0029)—, pero no hay una lectura que las combine y las filtre por el usuario, así que hoy el frontend tendría que cruzar varias llamadas y aplicar él mismo las reglas de visibilidad.
Combinarlas no es un simple listado: entran en juego tres filtros a la vez. La
empresa (todo lo que se lee es de la empresa del token), la habilitación
de la aplicación (rel_empresa_aplicacion) y los permisos del usuario
(las acciones que tiene concedidas en rel_usuario_accion, ADR 0023). Además,
root es el caso especial: su acceso es total por claim y no por lista de
acciones (ADR 0031).
El menú es jerárquico (cfg_menu.padre_id, hasta tres niveles, ADR 0022). Un
usuario al que se le concede una acción en un menú hijo no debe ver un árbol
cortado: si no viaja su menú padre, la entrada queda huérfana en el frontend.
Decisión¶
Se agrega el dominio dashboard con dos lecturas protegidas por JWT
(ADR 0031), montadas dentro del router protegido de create_app():
| Endpoint | Respuesta |
|---|---|
GET /api/v1/dashboard |
Aplicaciones con sus módulos |
GET /api/v1/dashboard/{modulo_id}/menu |
Menús jerárquicos del módulo con sus acciones |
Identidad desde el token, nunca del request¶
El usuario_id y el empresa_id salen del access token (UsuarioActual,
ADR 0031), no del cuerpo ni de la ruta. El endpoint recibe UsuarioActual por
Depends(get_current_user) y se lo pasa al service. Un request no puede pedir
el panel de otra empresa ni de otro usuario: cambiar la empresa exige un token
nuevo.
Root ve todo lo habilitado; el usuario sólo lo concedido¶
- root: todas las aplicaciones y módulos activos habilitados a la empresa,
ordenados por nombre. Una aplicación habilitada sin módulos viaja igual, con
modulosvacío. En el menú, todos los menús con todas sus acciones. - usuario normal: sólo las aplicaciones, módulos y acciones concedidas. Una
aplicación o un módulo sin concesión no se devuelve. En el menú, un menú
aparece si tiene acciones concedidas o si algún descendiente las tiene: se
incluyen los ancestros para no cortar la jerarquía, y viajan con
accionesvacío los que no tienen concesión propia.
Empresa siempre, aplicación habilitada siempre¶
Todas las consultas filtran empresa_id y exigen que la aplicación esté en
rel_empresa_aplicacion (activa). Un módulo o menú de otra empresa es
invisible: GET .../{modulo_id}/menu de un módulo ajeno responde 404
«Módulo no encontrado», sin distinguirlo de uno inexistente. Las consultas del
usuario suben por la jerarquía navegación (acción → menú → módulo → aplicación)
y exigen la aplicación habilitada, así que una concesión sobre una aplicación
deshabilitada no asoma.
El sujeto incluye el rol¶
rel_usuario_accion concede a un usuario o a su rol (ADR 0023). El
repository resuelve el tipo_usuario_id del usuario desde mae_usuarios y une
ambos caminos, de modo que el permiso efectivo del panel coincida con el que el
login calculó para el token.
El árbol se arma en el backend¶
El service agrupa los menús por padre_id (raíz = None), ordena por orden y
luego por codigo, y anida hijos recursivamente. El frontend recibe el árbol
listo para consumir y no replica reglas de visibilidad ni de jerarquía.
Alternativas descartadas¶
- Devolver listas planas y que el frontend arme el árbol — repartiría las reglas de root, empresa, aplicación habilitada y ancestros entre dos capas; cualquier cambio de autorización obligaría a tocar el frontend.
- Aceptar
empresa_idyusuario_idpor query — abre la puerta a leer el panel de otra empresa o de otro usuario; el token ya trae ambos. - Resolver los permisos sólo con el claim
permisos— el claim trae códigos de acción, no sumenu_id, y el código es único por menú, no global; sin la fila de la acción no se puede armar el árbol ni mapear la jerarquía. - Mostrar sólo el menú con la acción concedida, sin ancestros — dejaría el hijo huérfano y el frontend no sabría dónde colgarlo.
- Un endpoint por nivel (aplicaciones, luego módulos, luego menú) — obliga a varias llamadas para pintar una pantalla y repite el filtrado por permisos.
Consecuencias¶
- OpenAPI del servicio suma 2 endpoints bajo
/api/v1/dashboard. - El dominio
dashboardno tiene tablas propias: es un slice de lectura que cruza navegación, empresas y usuarios sólo-lectura, como el resto de las referencias entre dominios. - El tree se arma con los datos ya filtrados; si una concesión sobre un menú está activa pero el menú está borrado lógicamente, no aparece ni corta el árbol.
- La respuesta crece con la profundidad del menú (hasta 3 niveles por el
CHECKdecfg_menu), no hay paginación.
Qué no cubre¶
- Escribir navegación, permisos o habilitaciones: es un slice de lectura.
- Autorización por acción de cada endpoint (ADR 0031): acá sólo se filtra la navegación que el usuario ya tiene; no se valida que pueda invocar una acción, eso queda para el gateway o el servicio que la expone.
- RLS a nivel de base: el filtro por empresa es de aplicación, no de políticas de PostgreSQL.