Saltar a contenido

0058. Códigos jerárquicos de la navegación (path sin aplicación)

Estado: Aceptado Fecha: 2026-11-04 Autor: Duval Alcivar Módulo(s) afectado(s): app/domains/navegacion/, alembic/, tests/unit/navegacion/, docs/adr/

Contexto

Las acciones ya guardan su path completo (ventas.facturas.emitidas.crear, ADR 0029 y 0043), pero módulos y menús sólo guardaban su propio segmento (ventas, emitidas). Eso obliga a quien arma o compara códigos (el panel, el instalador de plantilla de core-frontend) a reconstruir el path por su cuenta, y deja el único (modulo_id, codigo) de menús frágil: dos submenús lista bajo padres distintos chocaban aunque fueran entidades distintas.

Decisión

Los códigos son paths jerárquicos sin el código de la aplicación:

  • módulo: ventas (segmento raíz, no cambia);
  • menú nivel 1/2/3: ventas.facturas, ventas.facturas.emitidas, ventas.facturas.emitidas.x;
  • acción: <path del menú>.<acción>.

Normalización. El cliente manda sólo el último segmento; si manda un path (ventas.facturas) se toma el último segmento. La reducción se hace en los contratos de entrada (field_validator de CfgModulos*, CfgMenu* y CfgMenuAcciones*, vía codigos.normalizar_segmento) y un segmento vacío, con espacios o de más de 50 caracteres responde 422. El service arma el path desde el padre (código del módulo, o del menú padre) y lo guarda; las respuestas devuelven el path. codigos.py concentra las funciones puras (segmento, path, descendientes) y las usa también la migración.

Cascada, en la misma transacción. Mover o reubicar menús (reordenar_menus y PUT /menu), cambiar el segmento de un menú o cambiar el código de un módulo recalcula el path de las entradas afectadas, de sus descendientes y de las acciones de todas ellas (NavegacionService._cascadear_codigos asigna en la sesión; el commit es el de la operación que la origina).

Filas borradas lógicamente. Los únicos (modulo_id, codigo) y (menu_id, codigo) son totales, así que la cascada incluye las filas borradas: se recalculan igual (reactivar una más tarde no encuentra un path viejo) y cuentan como ocupantes al validar duplicados.

Colisiones. Si el resultado repite un código dentro de su ámbito, se lanza CodigoDuplicadoError (409) antes de asignar nada: no se escribe ninguna fila.

Plantilla. PLANTILLA_BASE sigue declarando segmentos; al materializar y en GET /admin/plantilla (ADR 0044) los menús salen con path completo, como las acciones.

Migración 20261104_001. Ensancha cfg_menu.codigo a varchar(255) y convierte todas las filas (activas y borradas) con codigos.planificar_codigos: menú = código del módulo + último segmento por la cadena de padres; acción = path del menú + su último segmento. Es idempotente y, si algún resultado duplicara un código, falla antes de escribir con un error que lista los ids en conflicto. Corre con el rol dueño (ADR 0056), al que no le aplica la RLS. El downgrade vuelve los menús al último segmento (falla con error claro si dos menús de un módulo comparten segmento) y estrecha la columna.

Alternativas descartadas

  • Guardar sólo el segmento y componer el path al leer — cada consumidor tendría que recorrer la jerarquía; el permiso (rel_usuario_accion) y el claim permisos ya viajan como path.
  • Incluir el código de la aplicación en el path — los módulos ya son únicos por (empresa, aplicación) y el prefijo alargaría todos los códigos sin desambiguar nada dentro de un módulo.
  • Recalcular sólo filas activas — dejaría paths viejos en filas borradas y una reactivación posterior podría chocar con el único total.

Consecuencias

  • Aplicar con alembic upgrade head y reiniciar el servicio.
  • Todo lo que lee menu.codigo (árbol de navegación del dashboard y del usuario) ahora recibe el path completo, no el segmento: el frontend debe tratarlo como identificador, no como etiqueta.
  • Un cambio de código de módulo o de menú reescribe muchas filas en una transacción; el rechazo por colisión es todo o nada.

Qué no cubre

  • No cambia ids ni permisos concedidos: rel_usuario_accion referencia acciones por id.
  • No migra el código de la aplicación ni el de las variables del sistema.