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/menulista las entradas activas ordenadas pornivelyorden;GET /api/v1/navegacion/menu/{menu_id}devuelve una por suidUUID.POST /api/v1/navegacion/menucrea con201;PUT /api/v1/navegacion/menu/{menu_id}actualiza parcialmente;DELETE /api/v1/navegacion/menu/{menu_id}elimina lógicamente con204.- Validaciones del
POSTy delPUT: empresa_iddebe existir enmae_empresas→404«Empresa no encontrada».modulo_iddebe existir encfg_modulos→404«Módulo no encontrado».padre_iddebe existir encfg_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ónNivelInvalidoError, el primer caso422del servicio. codigoes único por(modulo_id, codigo)(constraint decfg_menu) → si se duplica,409«Ya existe una entrada de menú con ese código en el módulo».- El
PUTdistingue «padre_idomitido» de «padre_idenviado comonull» conmodel_fields_setde 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 flagset_padre_idque 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
CHECKde la base alcanzan para el CRUD. - Permitir niveles libres sin coherencia — rompería el
CHECKde 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
422del servicio. - El patrón
model_fields_setqueda documentado para futuros campos nullable-limpiables en losUPDATEde otros dominios.