CreaRack-SL

Onboarding guiado de descarga del Local Agent (PR #182, #293)

Vista limpiaEditar
Funcionalidadactivecreado Thu Jul 09#network#agent#frontend#ux#discovery#onboarding#javascript

Descripción

Feature que ofrece al usuario una descarga guiada y contextual del Local Agent cuando lo necesita, pero no está instalado en su equipo.

Cierra la brecha de UX en el flujo de auto-discovery de red: hasta ahora, si el Agent no estaba en ejecución, el usuario veía solo un error seco ("Please start CreaRackAgent.exe") sin opciones. Ahora:

  1. Se detecta que el Agent NO está corriendo (probe a 127.0.0.1:5050/info).
  2. Se muestra un banner instalación con dos botones: Download Local Agent y Not now.
  3. Al pulsar Download: se descarga el instalador .exe (descarga del navegador, automatizada), se sondea cada 2.5s, y se cierra el banner automáticamente cuando el Agent conecta.
  4. Se ofrece en contextos específicos (discovery de red, agent_probe) — modelo “just-in-time”, no al iniciar la app (pues hay usuarios que solo leen datos del Sentinel central, sin necesidad de Agent local).

Contexto de negocio

  • Tarea #182: Falta guía de instalación del Local Agent en primera instalación.
  • Modelo de despliegue: El navegador solo ve el Agent de SU máquina (127.0.0.1). El Sentinel 24/7 (Agent Primary) entrega monitorización central sin necesidad de Agent local en cada equipo. Por eso no hay aviso genérico al arrancar la app.
  • Deuda menor: Traducción ES de strings nuevos → ciclo i18n F4.

Componentes técnicos

Módulo principal: agent_onboarding.js

  • Ubicación: static/js/modules/agent_onboarding.js (114 LOC).
  • API pública: window.CreaRackAgentOnboarding:
    • offer(context) — muestra el banner de instalación. context puede ser 'discovery', 'manual' u otro.
    • downloadAgent() — descargar el .exe.
    • agentRunning() — probe ligero (fetch a /info con timeout 1.5s).
  • Polling: Cada 2.5s comprueba si el Agent conectó. Al conectar, cierra el banner y muestra un toast de éxito.
  • Estilos: Banner usa clase lna-notice (reutilizado de agent_lna_notice.js). Botones horizontales: .agent-install-actions (flexbox, gap 10px).

Integración en flujos existentes

  • discovery.js (línea ~255): En el catch del probeIpViaAgent, ofrece el onboarding en vez de lanzar error seco.
  • agent_probe.js (línea ~27): Igual — context 'discovery'.

Estilos CSS

  • components.css (19 LOC): Nueva clase .agent-install-actions para layout horizontal de botones.

Carga en HTML

  • base.html: Script defer tras agent_lna_notice.js, antes de auth.js.

Flujo UX

Usuario intenta discovery de red
    → agent_probe.js / discovery.js sondean Agent
        → Falla el fetch a 127.0.0.1:5050/info
            → En catch: CreaRackAgentOnboarding.offer('discovery')
                → Banner: "Install the Local Agent"
                → Botones: Download | Not now
                    → Download: descarga .exe, sondea cada 2.5s
                    → Not now: cierra banner (marca sesión para no reofrecerlo)

No auto-disparo al cargar la app: El usuario que solo consulta datos centrales nunca verá el banner (model just-in-time).

Detalles de implementación

Detección del Agent

async function agentRunning() {
    try {
        const r = await fetch(`${AGENT_URL}/info`, { 
            signal: AbortController, 
            timeout: 1500ms 
        });
        return r.ok;
    } catch { return false; }
}
  • Intro dinámico según context (discovery vs. manual).
  • Botones: btn-action (Download, en azul/primario) y btn-neutral (Not now, en gris).
  • Al hacer click en Download: el texto cambia a “Downloading…” y el botón se deshabilita.
  • El banner se remueve con animación fade-out (0.25s, clase lnaOut).

Polling

  • Cada 2.5s: agentRunning().
  • Al detectar conexión: limpiar intervalo, mostrar toast “Local Agent connected” (verde), remover banner.

Diferencias con agent_lna_notice.js

MóduloQué detectaCuándo se muestraAcción
agent_lna_notice.jsAgent YA instalado pero permiso Local Network Access pendientePrimera vez / consentimiento pendienteExplica el popup del navegador para aceptar permiso
agent_onboarding.js (nuevo)Agent NO instaladoCuando se necesita en un flujo (discovery, etc.)Ofrece descargar el instalador

Ambos usan el estilo .lna-notice (banner flotante en la app).

Verificación (testeado en local)

  • ✅ Banner en contexto discovery (probe falla).
  • ✅ Banner en contexto manual (offer() directo).
  • ✅ Download cambia estado y deshabilita botón.
  • ✅ Not now cierra + marca sesión.
  • ✅ Polling cierra al conectar Agent.
  • ✅ Toast de éxito “Local Agent connected”.
  • ✅ Sin errores de consola (Docker + navegador, admin).
  • ⚠️ Instalación sigue siendo manual (navegador no ejecuta .exe); descarga sí es automatizada.

Véase también

  • [[feature—core—aviso-lna]]
  • [[entity—static—service—agent-onboarding]]
  • [[concept—terminal—local-agent]]
  • [[decision—20260610—terminal-auth-local-cross-origin]]
  • [[feature—network—auto-provision-refresh-agent-fix]]

Referenciado desde

Inicio
Yo