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 claimpermisosya 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 heady 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_accionreferencia acciones por id. - No migra el código de la aplicación ni el de las variables del sistema.