Saltar a contenido

0022. CRUD de navegación — tercer slice: cfg_menu

Estado: Aceptado Fecha: 2026-09-29 Autor: Duval Alcivar Módulo(s) afectado(s): app/domains/navegacion/, tests/unit/navegacion/

Contexto

El ADR 0021 agregó cfg_modulos, el segundo eslabón de la cadena de dependencias de la navegación. Este ADR agrega el tercero: cfg_menu, las entradas de menú por empresa. A diferencia de los slices anteriores, el menú es jerárquico: padre_id se autorreferencia a cfg_menu (NULL en las de primer nivel) y la base limita la profundidad con un CHECK de nivel entre 1 y 3.

Decisión

Se implementa el CRUD de cfg_menu bajo /api/v1/navegacion/menu:

  • GET /api/v1/navegacion/menu lista las entradas activas ordenadas por nivel y orden; GET /api/v1/navegacion/menu/{menu_id} devuelve una por su id UUID.
  • POST /api/v1/navegacion/menu crea con 201; PUT /api/v1/navegacion/menu/{menu_id} actualiza parcialmente; DELETE /api/v1/navegacion/menu/{menu_id} elimina lógicamente con 204.
  • Validaciones del POST y del PUT:
  • empresa_id debe existir en mae_empresas → 404 «Empresa no encontrada».
  • modulo_id debe existir en cfg_modulos → 404 «Módulo no encontrado».
  • padre_id debe existir en cfg_menu → 404 «Entrada de menú padre no encontrada».
  • Coherencia de nivel: sin padre el nivel debe ser 1, y con padre debe ser nivel del padre + 1 → 422 «Nivel de menú inválido». Es la nueva excepción NivelInvalidoError, el primer caso 422 del servicio.
  • codigo es único por (modulo_id, codigo) (constraint de cfg_menu) → si se duplica, 409 «Ya existe una entrada de menú con ese código en el módulo».
  • El PUT distingue «padre_id omitido» de «padre_id enviado como null» con model_fields_set de Pydantic v2: si el campo se envió (aun en null) se asigna, lo que permite limpiar el padre; si se omitió, no se toca. El repository recibe el valor y un flag set_padre_id que marca esa semántica.

Alternativas descartadas

  • Validar el árbol completo en un solo paso — reordenar o validar la jerarquía completa (por ejemplo, detectar ciclos o rebalancear niveles) queda fuera del alcance de este slice; la validación local (padre + 1) más el CHECK de la base alcanzan para el CRUD.
  • Permitir niveles libres sin coherencia — rompería el CHECK de la base (nivel IN (1, 2, 3)) y dejaría árboles inconsistentes para el frontend.

Consecuencias

  • Desbloquea cfg_menu_acciones (ADR 0023): ya puede validar su referencia a entrada de menú contra un CRUD real.
  • OpenAPI del servicio suma 5 endpoints y el primer caso 422 del servicio.
  • El patrón model_fields_set queda documentado para futuros campos nullable-limpiables en los UPDATE de otros dominios.