# Plan de Arquitectura Técnica (SDD-011) ## Módulo: Servidor MCP y Asistente Interactivo Guiado (Walkthrough Spotlight) --- ### 1. Arquitectura del Sistema ```mermaid 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`: ```json { "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.