Saltar a contenido

0044. Endpoint de lectura de la plantilla base de navegación

Estado: Aceptado Fecha: 2026-10-12 Autor: Duval Alcivar Módulo(s) afectado(s): app/domains/navegacion/, docs/adr/

Contexto

La plantilla base de navegación (PLANTILLA_BASE, ADR 0034) describe, en código, el árbol aplicación → módulos → menú → acciones que se materializa al crear una empresa. Hasta ahora sólo la consumía la materialización: el frontend no tenía forma de leerla, así que no podía mostrar ese árbol ni dejar marcar qué se habilita a una empresa sin reimplementar la estructura del lado del cliente.

La plantilla es de la plataforma, no de una empresa: describe lo que el producto ofrece (las aplicaciones CORE, CRM y ERP con sus módulos y menús), no lo que una empresa tiene habilitado. Por eso no encaja en los endpoints existentes de navegación, que son por empresa (cfg_modulos, cfg_menu, ...).

Además, la plantilla declara sus campos de forma tolerante: lo que no se declara se asume (orden por índice, is_visible en True, nivel por profundidad), y el codigo de cada acción es el path completo (<codigo_modulo>.<path_menu>.<accion>), la forma que guarda cfg_menu_acciones.codigo (ADR 0029 y 0043).

Decisión

Se expone la plantilla por HTTP en solo lectura:

  • GET /api/v1/navegacion/plantilla devuelve list[PlantillaAplicacionRead], el árbol completo con acciones e hijos anidados.
  • Sin parámetros y sin empresa_id: es la plantilla de la plataforma, no de una empresa; pedirla no depende de ninguna habilitación.
  • El service resuelve los defaults antes de responder: orden cae en el índice del elemento, is_visible en True y nivel en la profundidad del menú (raíz del módulo = 1). El frontend recibe valores ya resueltos y no duplica las reglas de la plantilla.
  • El codigo de cada acción viaja como path completo, con la misma regla que _crear_menu usa al materializar (ADR 0034): así el frontend compara contra el código real que se concede en rel_usuario_accion sin rearmar el path.

NavegacionService.obtener_plantilla() es una proyección pura sobre PLANTILLA_BASE: no toca la base, no usa el repository y no hace commit.

Alternativas descartadas

  • Devolver la plantilla cruda (con los None sin resolver) — obligaría al frontend a replicar las reglas de default (orden/is_visible/nivel), que son del backend. Es el mismo reparto que el ADR 0037 descartó al rechazar «resolver el filtrado de módulos en el frontend».
  • Devolver el código corto de la acción (crear) — el frontend tendría que reimplementar la regla del path completo para poder comparar con cfg_menu_acciones.codigo. El código que viaja debe ser el que se concede.
  • Derivar la plantilla de la base (leer una empresa ya materializada) — mezclaría la plantilla de la plataforma con la navegación de una empresa y ataría la lectura a que exista al menos una empresa materializada.
  • Agregar empresa_id para filtrar — la plantilla es global; un filtro por empresa no tiene sentido sobre una estructura que todavía no existe para ella.

Consecuencias

  • El frontend puede mostrar el árbol aplicación → módulos → menú → acciones y dejar marcar qué se habilita a una empresa, sin reimplementar la estructura ni los defaults.
  • OpenAPI suma un endpoint de lectura.
  • El contrato queda atado a la forma de PLANTILLA_BASE: agregar un campo significa sumarlo al dataclass y al schema; el dueño ajusta la plantilla editándola (ADR 0034).
  • Sin pruebas por decisión del dueño: el cambio no agrega ni modifica tests. La verificación es ruff/mypy/pytest sobre el resto de la suite.

Qué no cubre

  • Habilitar o conceder nada: es sólo lectura; la materialización sigue en el alta de empresa (ADR 0034) y la concesión en rel_usuario_accion (ADR 0029).
  • La navegación de una empresa: los endpoints por empresa (ADR 0021–0024) siguen siendo los que devuelven lo habilitado a una empresa concreta.
  • Autorización por acción del endpoint: queda bajo el esquema Bearer común (ADR 0031 y 0039), sin código de permiso propio.