Files

4.8 KiB

Plan de Arquitectura Técnica (SDD-011)

Módulo: Servidor MCP y Asistente Interactivo Guiado (Walkthrough Spotlight)


1. Arquitectura del Sistema

graph TD
    subgraph "Cliente Web (Frontend BFF)"
        WIDGET[UdeCi Chat Widget]
        SPOTLIGHT[Spotlight & Walkthrough Engine (CSS/JS)]
        DOM[DOM de la Aplicación: Sedes, Aulas, Ciclos...]
    end

    subgraph "Backend Core FastAPI (:5000)"
        ROUTER[routers/ai_chat.py]
        GUIDE_SRV[services/guide_service.py]
        MCP_ROUTER[routers/mcp_server.py / mcp_endpoint]
    end

    subgraph "Servidor MCP Edu-Space (Python Standard MCP)"
        MCP_TOOLS[MCP Tools: inspect_routes, get_step_guide, get_ui_selectors]
    end

    subgraph "Inferencia Local (10.0.0.214:8080)"
        LLAMACPP[Llama.cpp Qwen3 30B (4 slots)]
    end

    WIDGET -->|1. Consulta del usuario / Iniciar Guía| ROUTER
    ROUTER -->|2. Obtiene directivas guiadas| GUIDE_SRV
    ROUTER -->|3. Prompt con herramienta de spotlight| LLAMACPP
    ROUTER -->|4. Retorna respuesta + guide_step| WIDGET
    WIDGET -->|5. Dispara iluminación visual| SPOTLIGHT
    SPOTLIGHT -->|6. Ilumina botón / espera click del usuario| DOM
    DOM -->|7. Usuario hace clic| SPOTLIGHT
    SPOTLIGHT -->|8. Notifica siguiente paso a UdeCi| WIDGET
    MCP_ROUTER -->|Protocolo MCP JSON-RPC| MCP_TOOLS

2. Capas y Componentes a Desarrollar

Capa 1: Servidor MCP Institucional (backend/mcp_server.py y backend/routers/mcp.py)

  • Servidor MCP compatible con especificación estándar Anthropic/Open MCP.
  • Herramientas (tools):
    1. get_application_routes: Lista las URLs canónicas y vistas del sistema.
    2. get_canonical_9_steps: Devuelve la secuencia exacta de 9 pasos con sus entidades y URLs.
    3. get_step_guide(action: str): Devuelve la lista ordenada de micro-pasos para acciones críticas (crear_sede, crear_aula, crear_ciclo, crear_comision, crear_reserva).
    4. get_ui_selectors(page: str): Mapea los botones y campos interactivos clave para cada vista.
  • Endpoint HTTP/JSON-RPC montado en FastAPI /api/v1/mcp para inspección de clientes y herramientas de agentes.

Capa 2: Servicio de Guías Interactivas (backend/app/services/guide_service.py)

  • Catálogo declarativo de pasos y selectores para las acciones clave:
    • Crear Sede: Ir a /buildings, iluminar #btnNewBuildingModal o [data-bs-target="#newBuildingModal"], iluminar campo #buildingName, iluminar #btnSaveBuilding.
    • Crear Aula: Ir a /classrooms, iluminar #btnCreateClassroom, iluminar campos de tipo/aforo, iluminar botón Guardar.
    • Crear Ciclo Lectivo: Ir a /admin/academic_periods, iluminar botón de nuevo período, etc.
  • Inyección de metadatos de guía en ChatResponse:
    {
      "response": "Para crear un aula nueva, haz clic en el botón '+ Nueva Aula' que he iluminado en la pantalla.",
      "quick_options": ["Siguiente paso", "Cancelar guía"],
      "guide_step": {
        "target_url": "/classrooms/list_classrooms",
        "selector": "#btnOpenCreateClassroomModal",
        "message": "Paso 1: Haz clic aquí para abrir el formulario de creación de aula.",
        "expected_action": "click",
        "step_number": 1,
        "total_steps": 3
      }
    }
    

Capa 3: Motor de Spotlight y Walkthrough en Frontend (frontend/public/js/walkthrough-engine.js y frontend/public/css/walkthrough.css)

  • Spotlight Visual:
    • Máscara oscura semitransparente (.walkthrough-backdrop) o halo luminoso con animación de pulso (.walkthrough-highlight).
    • Tarjeta flotante interactiva (.walkthrough-tooltip) anclada con Popper o posicionamiento dinámico sobre el elemento, con número de paso, botón de "Cerrar" y mensaje de UdeCi.
    • Scroll automático suave (element.scrollIntoView({ behavior: 'smooth', block: 'center' })).
    • Detección del evento de interacción del usuario (click / input): cuando el usuario hace la acción requerida, el halo emite un destello de éxito y avanza al siguiente paso.
  • Soporte Responsive (Desktop y Mobile):
    • Desktop: Spotlight completo con tooltip dinámico flotante.
    • Mobile (<768px): Barra guía fija inferior (Floating Guide Banner) con indicación clara y botón táctil destacado para evitar descalces de pantalla táctil.
  • Soporte de Contrastes en Modo Oscuro y Claro:
    • Modo Oscuro: Borde #ec4899 / #a855f7 brillante con resplandor box-shadow: 0 0 25px rgba(236, 72, 153, 0.6).
    • Modo Claro: Resplandor púrpura/magenta UniCABA #B43E8E sobre fondo de alto contraste con texto oscuro legible #1e293b.

Capa 4: Integración en UdeCi Chat Widget (frontend/views/partials/ai_chat_widget.html)

  • Cuando una guía está en curso, el chat widget se minimiza automáticamente a una píldora discreta o modo "Acompañante", para que el usuario tenga el 100% de la pantalla despejada para realizar la acción.