feat: servidor mcp institucional y asistente interactivo guiado con spotlight didactico (SDD-011, v3.8.27)
This commit is contained in:
@@ -0,0 +1,90 @@
|
||||
# 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.
|
||||
@@ -0,0 +1,44 @@
|
||||
# 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.
|
||||
@@ -0,0 +1,64 @@
|
||||
# Desglose de Tareas: Servidor MCP y Asistente Interactivo Guiado (SDD-011)
|
||||
|
||||
## Tareas de Implementación
|
||||
|
||||
- [x] **Tarea 1: Servidor MCP Institucional y Endpoints JSON-RPC / REST**
|
||||
- **Estimación**: 30 min
|
||||
- **Acciones**:
|
||||
- Crear `backend/mcp_server.py` implementando las herramientas MCP (`get_application_routes`, `get_canonical_9_steps`, `get_step_guide`, `get_ui_selectors`).
|
||||
- Crear `backend/routers/mcp.py` con endpoint `/api/v1/mcp` para ejecutar herramientas y listar recursos.
|
||||
- Registrar el router en `backend/main.py`.
|
||||
- **Hecho cuando**: Peticiones JSON-RPC / REST a `/api/v1/mcp` devuelven la lista de herramientas y la guía de pasos correcta con HTTP 200.
|
||||
|
||||
- [x] **Tarea 2: Servicio de Guías Interactivas y Esquemas Pydantic v2**
|
||||
- **Estimación**: 25 min
|
||||
- **Acciones**:
|
||||
- Actualizar `backend/schemas/ai_chat.py` con el modelo `GuideStepDTO` y el campo opcional `guide_step` en `ChatResponse`.
|
||||
- Crear `backend/app/services/guide_service.py` con los flujos canónicos:
|
||||
- Creación de Sede (`/buildings`)
|
||||
- Creación de Aula (`/classrooms/list_classrooms`)
|
||||
- Creación de Ciclo Lectivo (`/admin/academic_periods`)
|
||||
- Creación de Comisión y Reserva
|
||||
- Actualizar `backend/routers/ai_chat.py` para vincular intenciones guiadas al `guide_step`.
|
||||
- **Hecho cuando**: Una pregunta como "¿Cómo creo un aula?" retorna `guide_step` estructurado con selector, mensaje y URL de destino.
|
||||
|
||||
- [x] **Tarea 3: Motor de Spotlight y Estilos Responsive (Walkthrough Engine)**
|
||||
- **Estimación**: 35 min
|
||||
- **Acciones**:
|
||||
- Crear `frontend/public/css/walkthrough.css`:
|
||||
- Estilos para halo luminoso con animación de pulso (`.walkthrough-spotlight`).
|
||||
- Tooltip flotante de alto contraste para Modo Claro (`[data-bs-theme="light"]`) y Modo Oscuro (`[data-bs-theme="dark"]`).
|
||||
- Barra guía inferior responsive para móviles (< 768px).
|
||||
- Crear `frontend/public/js/walkthrough-engine.js`:
|
||||
- Métodos: `startStep(guideStep)`, `highlightElement(selector, message)`, `clearSpotlight()`.
|
||||
- Detección de clics para micro-feedback ("¡Muy bien!") y avance.
|
||||
- Botón "Ir a la pantalla" si el usuario no está en la página adecuada.
|
||||
- Vincular `walkthrough.css` y `walkthrough-engine.js` en `frontend/views/base.html`.
|
||||
- **Hecho cuando**: Al invocar `WalkthroughEngine.startStep(...)`, el elemento se ilumina en pantalla en modo claro/oscuro tanto en desktop como en móvil.
|
||||
|
||||
- [x] **Tarea 4: Integración del Motor Guiado con el Widget de Chat UdeCi**
|
||||
- **Estimación**: 25 min
|
||||
- **Acciones**:
|
||||
- Modificar `frontend/public/js/ai-chat-widget.js` para recibir `data.guide_step`.
|
||||
- Cuando `guide_step` esté presente, minimizar el panel del chat a modo flotante compacto y activar `WalkthroughEngine.startStep(data.guide_step)`.
|
||||
- Si el usuario está en otra URL, ofrecer redirección con guardado de paso en `sessionStorage` para continuar inmediatamente tras la carga.
|
||||
- **Hecho cuando**: UdeCi responde la explicación y automáticamente resalta el botón correspondiente en la aplicación.
|
||||
|
||||
- [x] **Tarea 5: Pruebas Automatizadas del Servidor MCP y Guías**
|
||||
- **Estimación**: 20 min
|
||||
- **Acciones**:
|
||||
- Crear `backend/tests/test_mcp_and_walkthrough.py`:
|
||||
- Pruebas de las herramientas MCP (`get_application_routes`, `get_step_guide`).
|
||||
- Pruebas del endpoint `/api/v1/mcp`.
|
||||
- Pruebas de integración de `guide_step` en `/api/chat`.
|
||||
- Ejecutar suite completa `pytest tests -v` y validar 100% verde (100 de 100 pasados).
|
||||
- **Hecho cuando**: Todas las pruebas automatizadas pasan exitosamente y 0 errores de compilación (`py_compile`).
|
||||
|
||||
- [x] **Tarea 6: Bump Semántico a v3.8.27, Git Push y Despliegue en Producción**
|
||||
- **Estimación**: 20 min
|
||||
- **Acciones**:
|
||||
- Bump semántico a `v3.8.27` en descriptores de versiones.
|
||||
- Actualizar `CHANGELOG.md` y `MEMORY.md`.
|
||||
- `git add .`, commit y `git push origin dev`.
|
||||
- Desplegar en producción LXC `10.0.0.217` y verificar en caliente con smoke test.
|
||||
- **Hecho cuando**: Producción corre en `v3.8.27` con el servidor MCP y el spotlight de UdeCi operativo.
|
||||
Reference in New Issue
Block a user