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/plantilladevuelvelist[PlantillaAplicacionRead], el árbol completo conaccionesehijosanidados.- 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:
ordencae en el índice del elemento,is_visibleenTrueynivelen 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
codigode cada acción viaja como path completo, con la misma regla que_crear_menuusa al materializar (ADR 0034): así el frontend compara contra el código real que se concede enrel_usuario_accionsin 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
Nonesin 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 concfg_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_idpara 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ú → accionesy 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/pytestsobre 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.