Saltar a contenido

0034. Plantilla base de navegación al crear una empresa

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

Contexto

La navegación es por empresa: cfg_modulos, cfg_menu y cfg_menu_acciones llevan empresa_id (ADR 0021, 0022 y 0023), y cat_aplicaciones es global (ADR 0020). Para que una empresa recién creada pueda conceder su primer permiso (ADR 0029) hace falta que existan sus módulos, sus páginas de menú y las acciones de cada página.

Hoy no existe nada de eso: al crear una empresa quedaba vacía, y armar su navegación era una tarea manual, fila por fila, antes de cualquier otra cosa. Además, los códigos de acción son un estándar de la plataforma: la acción que autoriza usuarios.crear debe llamarse igual en todas las empresas, si no cada una inventa su propio vocabulario y ninguna herramienta puede cruzarlo.

Por otro lado, las aplicaciones no son un catálogo abierto que cada empresa pueda poblar: la plataforma tiene siempre las mismas tres (CORE, CRM y ERP) y no crece más allá de lo que la plantilla referencia. Tampoco conviene fijarlas con id literal ni sembrarlas por migración: el id es de la base y una referencia literal obliga a mantenerla sincronizada a mano.

El objetivo de este cambio es doble: que la plantilla misma resuelva sus aplicaciones por código —buscándolas y creándolas sólo si faltan, con el id que genera la base— y que crear una empresa con el check materializar_plantilla activo deje armada una estructura de navegación básica con códigos de acción estándar.

Decisión

Resolución de aplicaciones por código

cat_aplicaciones sigue siendo global (ADR 0020), pero la plantilla ya no depende de un id fijo ni de una migración que la siembre. Cada AplicacionPlantilla describe la aplicación por código (codigo, nombre y, si hace falta, dominio, descripcion, icono), y una función dedicada, _obtener_aplicacion_id, resuelve el id al materializar:

  • busca la aplicación por codigo con NavegacionRepository.buscar_aplicacion_por_codigo;
  • si existe, devuelve su id y no toca nada;
  • si no existe, crea cat_aplicaciones con los datos de la plantilla, hace add + flush y devuelve el id.

El id nunca se asigna a mano (ni literal ni aleatorio): lo genera la base con su server_default uuidv7(), y el flush lo resuelve para poder referenciarlo dentro de la misma transacción. No hay migración de seed ni constantes de id: la plantilla se autocontiene y, al materializar, asegura que las tres aplicaciones que referencia (CORE, CRM y ERP) existan. Como el catálogo es de sistema y no crece más allá de lo que la plantilla referencia, esa búsqueda/creación es idempotente.

Plantilla declarativa

Se agrega la plantilla base declarativa en app/domains/navegacion/plantilla.py:

  • PLANTILLA_BASE describe, sin tocar la base, la estructura a crear: aplicación → módulos → menús → acciones, con dataclasses inmutables (AplicacionPlantilla, ModuloPlantilla, MenuPlantilla, AccionPlantilla). AplicacionPlantilla describe la aplicación por código (codigo, nombre y, opcionales, dominio, descripcion, icono): no lleva id, porque ese lo resuelve la materialización contra la base. MenuPlantilla anida por hijos, así que la plantilla cubre la jerarquía de cfg_menu de hasta tres niveles. La estructura inicial es de prueba: CORE con el módulo seguridad (menús usuarios —con los hijos listado, tipos-usuario y permisos— y empresas), CRM con los módulos clientes (menú clientes con el hijo listado) y fuerza-ventas (menú listado), y ERP sin módulos (el dueño lo completa después).
  • Mapeo completo de columnas con defaults tolerantes. Cada dataclass mapea las columnas de su tabla y los campos opcionales llevan default: lo que no se declara se asume (orden deriva del índice en su lista, is_visible cae en True, nivel deriva de la profundidad) y lo que se declara manda. Por eso los campos obligatorios van primero y los opcionales, con default, al final.
  • materializar_plantilla(db, empresa_id) recorre PLANTILLA_BASE: por cada aplicación resuelve su id por código con _obtener_aplicacion_id (la busca y, si no existe, la crea), habilita la rel_empresa_aplicacion si falta y crea módulos, menús y acciones. Los menús se crean recursivamente: el nivel sale de la profundidad (raíz del módulo = 1, cada hijo suma 1), el padre_id del menú que los contiene (None en el nivel 1) y el orden/is_visible de la plantilla o de su default. Un nivel explícito que no coincida con la profundidad, o una profundidad mayor a tres, lanzan NivelPlantillaInvalidoError (el CHECK de la tabla es 1..3).
  • El código estándar de cada acción es el path completo dentro del módulo: <codigo_modulo>.<codigo_menu_nivel1>[.<nivel2>[.<nivel3>]].<codigo_accion> (por ejemplo seguridad.usuarios.crear, seguridad.usuarios.listado.ver o seguridad.usuarios.permisos.conceder), que es el valor que después se concede en rel_usuario_accion. El código de la aplicación no forma parte del path. El nombre legible es la acción capitalizada (Ver, Listar, Crear, …) y el metodo_http se sugiere por acción CRUD (GET/POST/PUT/DELETE); las no-CRUD (conceder, revocar) quedan sin método.

El alta de empresa (ADR 0016) suma el flag materializar_plantilla en MaeEmpresasCreate (por defecto false) y un método EmpresaRepository.crear_empresa_con_plantilla. Cuando el check viene activo, el service excluye el flag del payload del ORM (no es columna) y delega en ese método; cuando no, se conserva el crear_empresa de siempre.

La materialización es atómica: el repository hace add + flush de la empresa (para tener su id), materializa la plantilla y recién ahí hace un solo commit con refresh. Si algo de la plantilla falla, la empresa no queda creada. La plantilla no hace commit por su cuenta: sólo flush, que es lo que necesita para resolver las referencias.

El ciclo completo queda así: se crea la empresa con el check → se materializa su estructura de navegación → a partir de ahí se conceden acciones a usuarios o roles con el código estándar.

Alternativas descartadas

  • Sembrar la navegación por migración para las empresas existentes — no todas usan lo mismo y la migración fijaría una estructura que cada empresa querría distinta; además no resuelve las empresas que se creen después.
  • Crear acción por acción a mano al dar de alta — es exactamente la fricción que se elimina; multiplica la probabilidad de códigos fuera del estándar.
  • Catálogo de permisos global por dominio — no corresponde: el permiso se concede sobre acciones que cuelgan de una página del menú de una empresa, no sobre un dominio suelto (ADR 0023).
  • Sembrar cat_aplicaciones por migración con id fijo — obliga a mantener a mano ids literales que deben coincidir entre la migración, las constantes y cualquier referencia, y crea una dependencia de un dato que la propia plantilla puede resolver. La plantilla se autocontiene: busca por código y crea si falta, con el id de la base.

Consecuencias

  • La plataforma tiene tres aplicaciones (CORE, CRM y ERP); no crece más allá de lo que la plantilla referencia. Agregar una cuarta exige sumarla a PLANTILLA_BASE, no una migración de siembra.
  • La materialización asegura la existencia de esas aplicaciones: si no estaban en cat_aplicaciones, las crea con el id que genera la base. La búsqueda por código es la que garantiza que no se dupliquen.
  • La plantilla es básica/de prueba: el dueño la ajusta editando PLANTILLA_BASE (agregar módulos, menús, hijos o acciones), sin tocar la lógica de materialización.
  • El path completo de la acción es el contrato de permisos: cambia si el menú cambia de módulo, de padre o de nombre, así que renombrar o mover un menú invalida los permisos ya concedidos sobre sus acciones.
  • La repetición por empresa es a propósito: cada una tiene sus propias filas de módulos, menú y acciones, porque son las que habilitan la concesión de permisos y el aislamiento por RLS.
  • Gotcha (verificar en entorno): cfg_modulos, cfg_menu y cfg_menu_acciones tienen RLS por app.current_empresa_id, y este código no setea esa variable. Si el rol de la aplicación la exige, la materialización fallará; hoy el patrón del servicio es que el filtro se resuelva fuera. Hay que confirmarlo contra la base antes de fiarse del alta con plantilla.
  • Las acciones quedan listas para conceder: a partir de la empresa creada, se puede poblar rel_usuario_accion con los códigos de la plantilla.

Qué no cubre

  • La autorización por endpoint: con qué código protege cada ruta cada servicio se definirá después, tomando como fuente los códigos que salgan de la plantilla.
  • La resolución de cat_aplicaciones más allá de las tres de la plantilla: el CRUD de aplicaciones (ADR 0020) sigue existiendo, pero la plantilla sólo asegura las que declara (CORE, CRM y ERP). Si mañana hiciera falta una cuarta aplicación, se agrega a PLANTILLA_BASE; el id lo sigue generando la base.