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
codigoconNavegacionRepository.buscar_aplicacion_por_codigo; - si existe, devuelve su
idy no toca nada; - si no existe, crea
cat_aplicacionescon los datos de la plantilla, haceadd+flushy devuelve elid.
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_BASEdescribe, sin tocar la base, la estructura a crear: aplicación → módulos → menús → acciones, con dataclasses inmutables (AplicacionPlantilla,ModuloPlantilla,MenuPlantilla,AccionPlantilla).AplicacionPlantilladescribe la aplicación por código (codigo,nombrey, opcionales,dominio,descripcion,icono): no llevaid, porque ese lo resuelve la materialización contra la base.MenuPlantillaanida porhijos, así que la plantilla cubre la jerarquía decfg_menude hasta tres niveles. La estructura inicial es de prueba: CORE con el móduloseguridad(menúsusuarios—con los hijoslistado,tipos-usuarioypermisos— yempresas), CRM con los módulosclientes(menúclientescon el hijolistado) yfuerza-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 (
ordenderiva del índice en su lista,is_visiblecae enTrue,nivelderiva 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)recorrePLANTILLA_BASE: por cada aplicación resuelve suidpor código con_obtener_aplicacion_id(la busca y, si no existe, la crea), habilita larel_empresa_aplicacionsi falta y crea módulos, menús y acciones. Los menús se crean recursivamente: elnivelsale de la profundidad (raíz del módulo = 1, cada hijo suma 1), elpadre_iddel menú que los contiene (Noneen el nivel 1) y elorden/is_visiblede la plantilla o de su default. Unnivelexplícito que no coincida con la profundidad, o una profundidad mayor a tres, lanzanNivelPlantillaInvalidoError(elCHECKde la tabla es1..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 ejemploseguridad.usuarios.crear,seguridad.usuarios.listado.veroseguridad.usuarios.permisos.conceder), que es el valor que después se concede enrel_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 elmetodo_httpse 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_aplicacionespor migración conidfijo — 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 elidde 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 elidque 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_menuycfg_menu_accionestienen RLS porapp.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_accioncon 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_aplicacionesmá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 aPLANTILLA_BASE; elidlo sigue generando la base.