Saltar a contenido

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 modulos vací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 acciones vací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_id y usuario_id por 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 su menu_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 dashboard no 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 CHECK de cfg_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.