Files

45 lines
4.6 KiB
Markdown

# Especificación de Requisitos de Software (SDD-011)
## Módulo: Servidor MCP y Asistente Interactivo Guiado (Walkthrough Spotlight) para UdeCi
**ID de Especificación**: SDD-011
**Estado**: En Progreso
**Fecha**: 2026-10-27
**Autores**: Coordinador de Arquitectura & Antigravity
---
### 1. Visión General y Propósito
El Asistente Virtual **UdeCi** evoluciona de un chatbot puramente conversacional hacia un **Tutor Interactivo en Vivo** ("enseñar a pescar, no dar el pescado"). El agente debe ser capaz de guiar al usuario paso a paso a través de la interfaz web de Admin Edu-Space (UniCABA), iluminando visualmente botones, formularios y controles en tiempo real (Spotlight / Element Glow) para que sea el propio usuario quien ejecute cada acción (guardar, seleccionar, aplicar, continuar).
Para lograr esto, se incorpora:
1. Un **Servidor MCP (Model Context Protocol)** institucional que expone recursos y herramientas (`tools`) de inspección de la aplicación (rutas canónicas, flujo de 9 pasos, selectores de UI y validaciones de estado).
2. Un **Motor de Directivas Guiadas en Frontend (Walkthrough / Spotlight Engine)** con soporte responsive (Desktop y Mobile) y soporte exhaustivo de contraste en Modo Oscuro y Modo Claro institucional.
3. Un canal de comunicación estructurado entre UdeCi y el DOM del usuario para resaltar elementos, verificar clics y transicionar fluidamente al siguiente paso formativo.
---
### 2. Requisitos del Sistema en Sintaxis EARS (Español)
#### 2.1 Requisitos Ubicuos (Ubiquitous Requirements)
- **REQ-UBI-01**: El sistema SIEMPRE preservará la soberanía del usuario: UdeCi guiará, explicará e iluminará el elemento de la UI, pero NUNCA enviará formularios ni presionará botones de confirmación por el usuario.
- **REQ-UBI-02**: El servidor MCP institucional SIEMPRE implementará el protocolo estándar MCP (Model Context Protocol) exponiendo herramientas para inspeccionar rutas, flujos de 9 pasos y estado de elementos.
- **REQ-UBI-03**: La interfaz gráfica del chat y del spotlight SIEMPRE cumplirá con los contrastes de accesibilidad WCAG AA tanto en Modo Claro (`[data-bs-theme="light"]`) como en Modo Oscuro (`[data-bs-theme="dark"]`).
#### 2.2 Requisitos Basados en Eventos (Event-driven Requirements)
- **REQ-EVT-01**: CUANDO el usuario solicite asistencia guiada ("¿Cómo creo un aula?", "¿Cómo registro una sede?", "¿Cómo configuro un ciclo?"), EL SISTEMA responderá con la explicación paso a paso y emitirá una directiva de guía interactiva (`guide_action`).
- **REQ-EVT-02**: CUANDO el frontend reciba una directiva `guide_action`, EL SISTEMA activará el efecto Spotlight sobre el selector CSS correspondiente (borde pulsante, halo de luz y tooltip explicativo) y navegará o desplazará suavemente la pantalla hacia el elemento.
- **REQ-EVT-03**: CUANDO el usuario presione el elemento iluminado o complete el paso, EL SISTEMA detectará la interacción, emitirá un micro-feedback positivo ("¡Excelente!") y desplegará la instrucción del siguiente paso.
- **REQ-EVT-04**: CUANDO el usuario presione el botón de "Cerrar guía" o "Cancelar spotlight", EL SISTEMA removerá de inmediato todos los halos de luz y tooltips de la pantalla sin interrumpir la navegación.
#### 2.3 Requisitos de Estado (State-driven Requirements)
- **REQ-STA-01**: MIENTRAS una guía interactiva esté activa, EL SISTEMA mantendrá el widget de chat minimizado o acoplado de forma flotante para no obstruir los formularios ni los modales en pantalla.
- **REQ-STA-02**: MIENTRAS la aplicación se visualice en dispositivos móviles (pantallas < 768px), EL SISTEMA adaptará el chat y el spotlight como una barra de guía inferior (*Bottom Sheet / Guide Bar*) con botones táctiles de al menos 44px de altura.
#### 2.4 Requisitos de Situaciones No Deseadas (Unwanted Behaviour Requirements)
- **REQ-NO-01**: SI el selector CSS indicado por el agente no existe en la página actual (por ejemplo, el usuario está en otra vista), EL SISTEMA ofrecerá un botón directo para redirigir automáticamente al usuario a la página correcta antes de intentar iluminar el elemento.
- **REQ-NO-02**: SI el usuario pierde la conexión o el servidor Llama.cpp experimenta alta latencia, EL SISTEMA mantendrá los pasos de la guía almacenados localmente para permitir que el usuario continúe sin bloqueo.
#### 2.5 Requisitos Opcionales (Optional Features)
- **REQ-OPC-01**: EN CASO DE QUE el usuario solicite un paseo general por el sistema, EL SISTEMA podrá iniciar el "Tour Oficial de los 9 Pasos de Bedelía" recorriendo Sedes, Aulas, Ciclos, Carreras, Asignaturas, Comisiones, Profesores, Alumnos y Reservas.