4.8 KiB
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):get_application_routes: Lista las URLs canónicas y vistas del sistema.get_canonical_9_steps: Devuelve la secuencia exacta de 9 pasos con sus entidades y URLs.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).get_ui_selectors(page: str): Mapea los botones y campos interactivos clave para cada vista.
- Endpoint HTTP/JSON-RPC montado en FastAPI
/api/v1/mcppara 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#btnNewBuildingModalo[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.
- Crear Sede: Ir a
- 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 conPoppero 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.
- Máscara oscura semitransparente (
- 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/#a855f7brillante con resplandorbox-shadow: 0 0 25px rgba(236, 72, 153, 0.6). - Modo Claro: Resplandor púrpura/magenta UniCABA
#B43E8Esobre fondo de alto contraste con texto oscuro legible#1e293b.
- Modo Oscuro: Borde
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.