feat: servidor mcp institucional y asistente interactivo guiado con spotlight didactico (SDD-011, v3.8.27)

This commit is contained in:
2026-10-27 08:23:04 -03:00
parent a5b014efbe
commit bf5b7c3ae7
20 changed files with 1339 additions and 12 deletions
+24
View File
@@ -11,6 +11,30 @@ El formato está basado en [Keep a Changelog](https://keepachangelog.com/es-ES/1
- **Sincronización Continua Moodle (Fase 6):** Automatización de workers persistentes en background para el procesamiento continuo de la cola de Web Services Moodle 4.1.
- **Pruebas de Carga y Hardening (Fase 6):** Pruebas de estrés de concurrencia y validación final de producción.
## [3.8.27] - 2026-10-27
### Added & Enhanced (Servidor MCP Institucional y Asistente Interactivo Guiado con Spotlight - SDD-011)
- **Servidor MCP Institucional (Model Context Protocol)**:
- Implementado `EduSpaceMCPServer` en `backend/mcp_server.py` compatible con estándares JSON-RPC 2.0 y REST.
- Herramientas MCP expuestas:
* `get_application_routes`: Lista las rutas canónicas y vistas del sistema según el rol.
* `get_canonical_9_steps`: Devuelve la secuencia estandarizada de 9 pasos de Bedelía con descripciones y prerrequisitos.
* `get_step_guide`: Guías interactivas paso a paso (`crear_sede`, `crear_aula`, `crear_ciclo`, `consultar_cursada`).
- Router FastAPI `backend/routers/mcp.py` montado en `/api/v1/mcp` y `/api/mcp`.
- **Filosofía Didáctica: "Enseñar a Pescar, No Dar el Pescado"**:
- `GuideService` (`backend/app/services/guide_service.py`): Inyección estructurada de `GuideStepDTO` (`target_url`, `selector`, `message`, `expected_action`, `step_number`, `total_steps`).
- UdeCi guía, explica e ilumina el botón o campo de la UI, pero es el usuario quien ejecuta el clic de confirmación, guardado o selección.
- **Motor de Spotlight y Walkthrough Responsive (Desktop & Mobile)**:
- `frontend/public/css/walkthrough.css`:
* Halo luminoso animado (`.walkthrough-highlight`) con resplandor magenta oficial `#B43E8E` en Modo Claro (`[data-bs-theme="light"]`) y neón fucsia `#d946ef` en Modo Oscuro (`[data-bs-theme="dark"]`).
* Tooltip flotante cristalino con backdrop blur y pasos enumerados.
* Barra guía inferior táctil (*Bottom Guide Banner*) para pantallas móviles (< 768px) con botones de altura ergonómica (mínimo 44px).
- `frontend/public/js/walkthrough-engine.js`:
* Detección de página actual y banner de redirección con persistencia de paso pendiente en `sessionStorage`.
* Detección de clics para micro-feedback ("¡Muy bien!") y avance de paso.
- **Calidad y Verificación Automatizada**:
- Creada suite `backend/tests/test_mcp_and_walkthrough.py` (5 pruebas unitarias e integración pasando al 100%).
- Suite completa de backend: **100 pruebas aprobadas** (`100 passed`), 0 errores de tipado o compilación.
## [3.8.26] - 2026-10-27
### Fixed & Enhanced (Aislamiento Individual y Simultáneo de Conversaciones en UdeCi)
- **Aislamiento Estricto de Conversaciones por Usuario Individual**:
+6 -5
View File
@@ -9,11 +9,12 @@ Memoria del proyecto entre sesiones para la rama `dev`.
- Libro de Calificaciones (*Gradebook*) con actas de regularidad inmutables.
- Autenticación híbrida (Google OAuth 2.0, Moodle SSO, Local) y Modo Impersonación.
- Reinicialización segura del sistema con contraseña de Administrador.
- **Sprint Activo: Arquitectura RAG Embebida y Conversaciones Individuales Aisladas — SDD-010 (v3.8.26)**:
- **Aislamiento Individual por Usuario en UdeCi**: Eliminada la clave de almacenamiento compartida en frontend. Cada usuario almacena su historial bajo `edu_space_udeci_chat_usr_<userId>`. En sesiones anónimas se asigna UUID por pestaña.
- **Inferencia Concurrente Simultánea**: `routers/ai_chat.py` inyecta `"user": user_identifier` y `conversation_id` en las peticiones a Llama.cpp, asegurando que los 4 slots de inferencia paralelos de la GPU operen de forma totalmente aislada sin colisión de KV Cache.
- **QA & Pruebas Automatizadas**: 95 tests aprobados al 100% en `pytest` (`95 passed`), 0 errores de tipado o compilación estática.
- **Versión Consolidada**: `v3.8.26`.
- **Sprint Activo: Servidor MCP y Asistente Interactivo Guiado con Spotlight — SDD-011 (v3.8.27)**:
- **Servidor MCP Institucional (`mcp_server.py` & `routers/mcp.py`)**: Protocolo MCP compatible con JSON-RPC 2.0 y REST en `/api/v1/mcp` con herramientas `get_application_routes`, `get_canonical_9_steps` y `get_step_guide`.
- **Filosofía Didáctica ("Enseñar a Pescar")**: `GuideService` emite `guide_step` con selectores CSS y mensajes formativos para guiar al usuario e iluminar las acciones en tiempo real, dejando que el usuario presione el botón.
- **Spotlight & Walkthrough Engine**: `walkthrough.css` y `walkthrough-engine.js` con halo luminoso pulsante, tooltips cristalinos, barra inferior móvil (<768px) y contraste validado en Modo Claro (Magenta UniCABA #B43E8E) y Modo Oscuro (#d946ef).
- **QA & Pruebas Automatizadas**: 100 tests aprobados al 100% en `pytest` (`100 passed`), 0 errores de tipado o compilación estática.
- **Versión Consolidada**: `v3.8.27`.
## Decisiones (y por qué)
- **Flujo Secuencial de Bedelía (9 Pasos)**: Estandarizar la carga operativa en: 1) Sede -> 2) Aula -> 3) Ciclo Lectivo -> 4) Carrera -> 5) Materia (vinculada a Carrera) -> 6) Comisión (asociada a Materia, Carrera y Ciclo) -> 7) Profesores -> 8) Alumnos -> 9) Reserva de Espacio. Esto asegura consistencia e integridad relacional.
+1 -1
View File
@@ -7,7 +7,7 @@ from typing import Any
from database import db, get_db, engine, SessionLocal, session
from config.config import Config
__version__ = "3.8.26"
__version__ = "3.8.27"
class DummyContext:
def __enter__(self):
+85
View File
@@ -0,0 +1,85 @@
"""
app/services/guide_service.py - Servicio de Guías Interactivas y Spotlight para UdeCi (SDD-011)
Detecta intenciones de tutorial paso a paso y emite directivas estructuradas
para que el frontend ilumine los botones y campos interactivos ("enseñar a pescar").
"""
import re
import unicodedata
from typing import Optional
from schemas.ai_chat import GuideStepDTO
from mcp_server import STEP_GUIDES
def _normalize(text: str) -> str:
"""Elimina acentos y pasa a minúsculas para matching semántico tolerante."""
nfkd = unicodedata.normalize('NFKD', text)
return ''.join([c for c in nfkd if not unicodedata.combining(c)]).lower()
class GuideService:
"""Servicio de resolución de pasos y directivas de UI para el asistente UdeCi."""
@classmethod
def detect_guide_step(cls, query: str, user_role: str = "alumno") -> Optional[GuideStepDTO]:
"""
Analiza la consulta del usuario y retorna el primer paso interactivo
si el usuario solicita aprender a realizar una acción en el sistema.
"""
if not query:
return None
q = _normalize(query)
# Acción: Crear Aula
if "aula" in q and ("crear" in q or "nueva" in q or "nuevo" in q or "alta" in q or "como" in q or "registrar" in q):
guide = STEP_GUIDES["crear_aula"]
step1 = guide["steps"][0]
return GuideStepDTO(
target_url=guide["target_url"],
selector=step1["selector"],
message=step1["message"],
expected_action=step1["expected_action"],
step_number=1,
total_steps=len(guide["steps"])
)
# Acción: Crear Sede
if ("sede" in q or "edificio" in q) and ("crear" in q or "nueva" in q or "nuevo" in q or "alta" in q or "registrar" in q or "como" in q):
guide = STEP_GUIDES["crear_sede"]
step1 = guide["steps"][0]
return GuideStepDTO(
target_url=guide["target_url"],
selector=step1["selector"],
message=step1["message"],
expected_action=step1["expected_action"],
step_number=1,
total_steps=len(guide["steps"])
)
# Acción: Crear Ciclo Lectivo
if ("ciclo" in q or "periodo" in q) and ("crear" in q or "nuevo" in q or "alta" in q or "como" in q or "registrar" in q):
guide = STEP_GUIDES["crear_ciclo"]
step1 = guide["steps"][0]
return GuideStepDTO(
target_url=guide["target_url"],
selector=step1["selector"],
message=step1["message"],
expected_action=step1["expected_action"],
step_number=1,
total_steps=len(guide["steps"])
)
# Acción: Consultar Cursada de Hoy (para Alumnos / Docentes)
if ("donde curso" in q or "aula de cursada" in q or "clases de hoy" in q or "aula de hoy" in q or "horario de hoy" in q):
guide = STEP_GUIDES["consultar_cursada"]
step1 = guide["steps"][0]
return GuideStepDTO(
target_url=guide["target_url"],
selector=step1["selector"],
message=step1["message"],
expected_action=step1["expected_action"],
step_number=1,
total_steps=len(guide["steps"])
)
return None
+3
View File
@@ -20,6 +20,7 @@ from routers.students import students_router
from routers.dashboard import dashboard_router
from routers.optimizer import optimizer_router, genetic_router
from routers.ai_chat import router as ai_chat_router
from routers.mcp import router as mcp_router
# Initialize FastAPI Application
app = FastAPI(
@@ -54,6 +55,8 @@ app.include_router(optimizer_router)
app.include_router(genetic_router)
app.include_router(ai_chat_router, prefix="/api/chat")
app.include_router(ai_chat_router, prefix="/api/v1/chat")
app.include_router(mcp_router, prefix="/api/mcp")
app.include_router(mcp_router, prefix="/api/v1/mcp")
if __name__ == "__main__":
+257
View File
@@ -0,0 +1,257 @@
"""
mcp_server.py - Servidor Model Context Protocol (MCP) para Admin Edu-Space (UniCABA)
Expone herramientas canónicas y de inspección de la aplicación para que agentes de IA
puedan guiar a los usuarios interactivamente en el uso del sistema.
"""
from typing import Dict, Any, List, Optional
CANONICAL_ROUTES = [
{"name": "Dashboard Principal", "path": "/dashboard", "roles": ["ADMIN", "DOCENTE", "ALUMNO", "BEDELIA"]},
{"name": "Paso 1: Sedes y Edificios", "path": "/buildings", "roles": ["ADMIN", "BEDELIA"]},
{"name": "Paso 2: Aulas Físicas y Virtuales", "path": "/classrooms/list_classrooms", "roles": ["ADMIN", "BEDELIA", "DOCENTE"]},
{"name": "Paso 3: Ciclos Lectivos", "path": "/admin/academic_periods", "roles": ["ADMIN", "BEDELIA"]},
{"name": "Paso 4: Carreras", "path": "/admin/careers", "roles": ["ADMIN", "BEDELIA"]},
{"name": "Paso 5: Asignaturas", "path": "/admin/subjects", "roles": ["ADMIN", "BEDELIA"]},
{"name": "Paso 6: Comisiones", "path": "/admin/commissions", "roles": ["ADMIN", "BEDELIA"]},
{"name": "Paso 7: Profesores y Docentes", "path": "/admin/professors", "roles": ["ADMIN", "BEDELIA"]},
{"name": "Paso 8: Alumnos y Matrícula", "path": "/admin/students", "roles": ["ADMIN", "BEDELIA"]},
{"name": "Paso 9: Reserva de Espacios Áulicos", "path": "/schedule", "roles": ["ADMIN", "BEDELIA", "DOCENTE"]},
{"name": "Mis Materias", "path": "/my_subjects", "roles": ["ALUMNO", "DOCENTE"]},
{"name": "Cartelera de Cursada de Hoy", "path": "/schedule/today_schedule", "roles": ["ALUMNO", "DOCENTE", "BEDELIA"]},
{"name": "Libro de Calificaciones (Gradebook)", "path": "/gradebook", "roles": ["DOCENTE", "ADMIN", "BEDELIA"]},
{"name": "Configuración Global", "path": "/admin/settings", "roles": ["ADMIN"]}
]
CANONICAL_9_STEPS = [
{
"step": 1,
"name": "Sedes",
"route": "/buildings",
"description": "Dar de alta la sede física o campus con nombre, dirección y código.",
"prerequisite": None
},
{
"step": 2,
"name": "Aulas",
"route": "/classrooms/list_classrooms",
"description": "Crear espacios físicos (con aforo y equipamiento) o virtuales (Google Meet).",
"prerequisite": "Sede física existente"
},
{
"step": 3,
"name": "Ciclos Lectivos",
"route": "/admin/academic_periods",
"description": "Definir el período académico (ej. 2026-1C) con fechas de inicio y fin.",
"prerequisite": None
},
{
"step": 4,
"name": "Carreras",
"route": "/admin/careers",
"description": "Registrar planes de estudio y carreras institucionales.",
"prerequisite": None
},
{
"step": 5,
"name": "Asignaturas",
"route": "/admin/subjects",
"description": "Dar de alta las materias y asociarlas a una o más carreras.",
"prerequisite": "Carrera existente"
},
{
"step": 6,
"name": "Comisiones",
"route": "/admin/commissions",
"description": "Crear las divisiones/comisiones de cada materia para el ciclo lectivo.",
"prerequisite": "Asignatura y Ciclo Lectivo activos"
},
{
"step": 7,
"name": "Profesores",
"route": "/admin/professors",
"description": "Asignar docentes titulares o adjuntos a las comisiones.",
"prerequisite": "Comisión activa"
},
{
"step": 8,
"name": "Alumnos",
"route": "/admin/students",
"description": "Matricular a los estudiantes en sus respectivas comisiones.",
"prerequisite": "Comisión activa"
},
{
"step": 9,
"name": "Reserva de Espacio",
"route": "/schedule",
"description": "Asignar aula y banda horaria validando la matriz de conflictos y aforo.",
"prerequisite": "Aula y Comisión completas"
}
]
STEP_GUIDES = {
"crear_sede": {
"title": "Guía: Cómo registrar una nueva Sede",
"target_url": "/buildings",
"steps": [
{
"step_number": 1,
"selector": "#btnNewBuildingModal, button[data-bs-target='#newBuildingModal'], a[href*='building']",
"message": "Paso 1: Haz clic en el botón '+ Nueva Sede' para abrir el formulario.",
"expected_action": "click"
},
{
"step_number": 2,
"selector": "#buildingName, input[name='name']",
"message": "Paso 2: Escribe el nombre institucional de la sede (ej. 'Sede Central').",
"expected_action": "input"
},
{
"step_number": 3,
"selector": "#btnSaveBuilding, button[type='submit']",
"message": "Paso 3: Haz clic en 'Guardar Sede' para confirmar el registro.",
"expected_action": "click"
}
]
},
"crear_aula": {
"title": "Guía: Cómo crear una nueva Aula (Física o Virtual)",
"target_url": "/classrooms/list_classrooms",
"steps": [
{
"step_number": 1,
"selector": "#btnOpenCreateClassroomModal, button[data-bs-target='#createClassroomModal'], .btn-create-classroom, a[href*='classrooms/new']",
"message": "Paso 1: Haz clic en el botón '+ Nueva Aula' para iniciar la creación.",
"expected_action": "click"
},
{
"step_number": 2,
"selector": "#classroomName, input[name='name']",
"message": "Paso 2: Ingresa el nombre o número de aula (ej. 'Aula 204') y define el aforo máximo de alumnos.",
"expected_action": "input"
},
{
"step_number": 3,
"selector": "#btnSaveClassroom, form#createClassroomForm button[type='submit'], .modal-footer .btn-primary",
"message": "Paso 3: Haz clic en 'Guardar Aula' para confirmar el alta.",
"expected_action": "click"
}
]
},
"crear_ciclo": {
"title": "Guía: Cómo dar de alta un Ciclo Lectivo",
"target_url": "/admin/academic_periods",
"steps": [
{
"step_number": 1,
"selector": "#btnNewPeriod, button[data-bs-target='#newPeriodModal'], .btn-new-period",
"message": "Paso 1: Haz clic en '+ Nuevo Ciclo Lectivo' para configurar el período académico.",
"expected_action": "click"
},
{
"step_number": 2,
"selector": "#periodCode, input[name='code']",
"message": "Paso 2: Ingresa el código del ciclo (ej. '2026-1C') y las fechas de inicio y fin.",
"expected_action": "input"
},
{
"step_number": 3,
"selector": "#btnSavePeriod, button[type='submit']",
"message": "Paso 3: Haz clic en 'Guardar Período' para habilitar la cursada.",
"expected_action": "click"
}
]
},
"consultar_cursada": {
"title": "Guía: Cómo consultar el aula de cursada de hoy",
"target_url": "/schedule/today_schedule",
"steps": [
{
"step_number": 1,
"selector": ".today-class-card, #todayScheduleContainer, .table-schedule",
"message": "Aquí puedes ver tus clases del día con el aula física asignada o el botón para unirte a Google Meet.",
"expected_action": "view"
}
]
}
}
class EduSpaceMCPServer:
"""Implementación del servidor MCP institucional para Edu-Space."""
@staticmethod
def get_tools_manifest() -> List[Dict[str, Any]]:
"""Retorna la lista de herramientas disponibles en el protocolo MCP."""
return [
{
"name": "get_application_routes",
"description": "Retorna la lista canónica de rutas, vistas y permisos de Admin Edu-Space.",
"parameters": {
"type": "object",
"properties": {
"role": {"type": "string", "description": "Filtro opcional por rol de usuario (ADMIN, DOCENTE, ALUMNO, BEDELIA)"}
}
}
},
{
"name": "get_canonical_9_steps",
"description": "Retorna la secuencia estandarizada de 9 pasos de Bedelía con descripciones y prerrequisitos.",
"parameters": {"type": "object", "properties": {}}
},
{
"name": "get_step_guide",
"description": "Obtiene la guía interactiva paso a paso con selectores CSS y acciones para iluminar la UI (enseñar a pescar).",
"parameters": {
"type": "object",
"properties": {
"action": {
"type": "string",
"enum": ["crear_sede", "crear_aula", "crear_ciclo", "consultar_cursada"],
"description": "Acción que el usuario desea aprender a realizar."
}
},
"required": ["action"]
}
}
]
@staticmethod
def execute_tool(name: str, arguments: Dict[str, Any]) -> Dict[str, Any]:
"""Ejecuta una herramienta del protocolo MCP y retorna su resultado."""
if name == "get_application_routes":
role_filter = arguments.get("role")
if role_filter:
r_upper = role_filter.upper()
routes = [r for r in CANONICAL_ROUTES if r_upper in r["roles"]]
else:
routes = CANONICAL_ROUTES
return {"routes": routes, "total": len(routes)}
elif name == "get_canonical_9_steps":
return {"steps": CANONICAL_9_STEPS, "total": len(CANONICAL_9_STEPS)}
elif name == "get_step_guide":
action = arguments.get("action", "").lower().strip()
# Mapeo semántico de intenciones
if "sede" in action or "edificio" in action:
key = "crear_sede"
elif "aula" in action:
key = "crear_aula"
elif "ciclo" in action or "periodo" in action:
key = "crear_ciclo"
elif "curso" in action or "clase" in action or "hoy" in action:
key = "consultar_cursada"
else:
key = action
guide = STEP_GUIDES.get(key)
if not guide:
return {
"error": f"No se encontró una guía interactiva para la acción '{action}'.",
"available_actions": list(STEP_GUIDES.keys())
}
return guide
else:
return {"error": f"Herramienta MCP desconocida: '{name}'"}
+4 -1
View File
@@ -12,6 +12,7 @@ from dependencies import get_optional_current_user, require_roles
from app.models.setting import SystemSetting
from app.models.user import User
from app.services.rag_service import RAGService
from app.services.guide_service import GuideService
from schemas.ai_chat import (
ChatRequest,
ChatResponse,
@@ -190,10 +191,12 @@ async def get_agent_response(
ai_data = response.json()
raw_reply = ai_data["choices"][0]["message"]["content"]
clean_reply, options = _extract_options_from_reply(raw_reply, effective_role)
guide_step = GuideService.detect_guide_step(last_query, effective_role)
return ChatResponse(
response=clean_reply,
quick_options=options,
conversation_id=user_identifier
conversation_id=user_identifier,
guide_step=guide_step
)
except httpx.TimeoutException:
raise HTTPException(
+100
View File
@@ -0,0 +1,100 @@
"""
routers/mcp.py - Router FastAPI para el Servidor MCP de Edu-Space (SDD-011)
Expone contratos OpenAPI y endpoints compatibles con JSON-RPC 2.0 y REST.
"""
from typing import Dict, Any, Optional
from fastapi import APIRouter, HTTPException, status
from pydantic import BaseModel, Field
from mcp_server import EduSpaceMCPServer
router = APIRouter(prefix="", tags=["Model Context Protocol (MCP)"])
class MCPToolExecutionRequest(BaseModel):
name: str = Field(..., description="Nombre de la herramienta MCP a ejecutar")
arguments: Optional[Dict[str, Any]] = Field(default_factory=dict, description="Parámetros de la herramienta")
class JSONRPCRequest(BaseModel):
jsonrpc: str = Field("2.0", description="Versión del protocolo JSON-RPC")
id: Optional[Any] = Field(None, description="Identificador de la petición")
method: str = Field(..., description="Método MCP: tools/list, tools/call")
params: Optional[Dict[str, Any]] = Field(default_factory=dict, description="Parámetros del método")
@router.get("/tools")
def list_mcp_tools():
"""Lista el catálogo de herramientas institucionales expuestas por el servidor MCP."""
return {
"status": "success",
"tools": EduSpaceMCPServer.get_tools_manifest()
}
@router.post("/execute")
def execute_mcp_tool(request: MCPToolExecutionRequest):
"""Ejecuta una herramienta del catálogo MCP de Edu-Space vía REST."""
result = EduSpaceMCPServer.execute_tool(request.name, request.arguments or {})
if "error" in result:
raise HTTPException(
status_code=status.HTTP_400_BAD_REQUEST,
detail=result["error"]
)
return {
"status": "success",
"tool": request.name,
"result": result
}
@router.post("")
@router.post("/")
def jsonrpc_mcp_endpoint(req: JSONRPCRequest):
"""
Endpoint estándar compatible con el protocolo MCP (JSON-RPC 2.0).
Soporta 'tools/list' y 'tools/call'.
"""
if req.jsonrpc != "2.0":
return {
"jsonrpc": "2.0",
"id": req.id,
"error": {"code": -32600, "message": "Versión JSON-RPC inválida, debe ser 2.0"}
}
if req.method in ["tools/list", "tools.list"]:
return {
"jsonrpc": "2.0",
"id": req.id,
"result": {
"tools": EduSpaceMCPServer.get_tools_manifest()
}
}
elif req.method in ["tools/call", "tools.call"]:
params = req.params or {}
name = params.get("name")
arguments = params.get("arguments", {})
if not name:
return {
"jsonrpc": "2.0",
"id": req.id,
"error": {"code": -32602, "message": "Parámetro 'name' requerido para tools/call"}
}
tool_result = EduSpaceMCPServer.execute_tool(name, arguments)
return {
"jsonrpc": "2.0",
"id": req.id,
"result": {
"content": [{"type": "text", "text": str(tool_result)}],
"data": tool_result
}
}
else:
return {
"jsonrpc": "2.0",
"id": req.id,
"error": {"code": -32601, "message": f"Método MCP no soportado: '{req.method}'"}
}
+10
View File
@@ -13,10 +13,20 @@ class ChatRequest(BaseModel):
conversation_id: Optional[str] = Field(None, description="Identificador único de conversación o sesión del usuario")
class GuideStepDTO(BaseModel):
target_url: str = Field(..., description="Ruta relativa de la vista de Edu-Space")
selector: str = Field(..., description="Selector CSS del elemento a iluminar con el Spotlight")
message: str = Field(..., description="Instrucción del paso para que el usuario actúe")
expected_action: str = Field("click", description="Acción del usuario: click, input, view")
step_number: int = Field(1, ge=1, description="Número de paso actual")
total_steps: int = Field(1, ge=1, description="Cantidad total de pasos")
class ChatResponse(BaseModel):
response: str = Field(..., description="Respuesta generada por el agente conversacional")
quick_options: Optional[List[str]] = Field(default_factory=list, description="Lista de opciones o preguntas sugeridas para botones interactivos")
conversation_id: Optional[str] = Field(None, description="Identificador único de conversación o sesión del usuario")
guide_step: Optional[GuideStepDTO] = Field(None, description="Directiva de Spotlight interactivo para guiar al usuario e iluminar elementos")
class RAGReindexResponse(BaseModel):
+1 -1
View File
@@ -2,7 +2,7 @@ from setuptools import setup, find_packages
setup(
name="edu-space-admin",
version="3.8.26",
version="3.8.27",
description="Administrative interface for Edu-Space Classroom Management System (FastAPI ASGI Core)",
author="Edu-Space Development Team",
author_email="admin@edu-space.com",
+153
View File
@@ -0,0 +1,153 @@
"""
backend/tests/test_mcp_and_walkthrough.py - Pruebas para el Servidor MCP y Walkthrough (SDD-011)
Valida herramientas MCP institucionales, endpoints JSON-RPC 2.0 / REST y directivas de Spotlight.
"""
from unittest.mock import AsyncMock, patch, MagicMock
import pytest
from fastapi.testclient import TestClient
from main import app
from mcp_server import EduSpaceMCPServer
from app.services.guide_service import GuideService
def test_mcp_server_manifest_and_execution():
"""Valida el manifiesto de herramientas MCP y la ejecución local."""
manifest = EduSpaceMCPServer.get_tools_manifest()
assert len(manifest) >= 3
tool_names = [t["name"] for t in manifest]
assert "get_application_routes" in tool_names
assert "get_canonical_9_steps" in tool_names
assert "get_step_guide" in tool_names
# 1. get_application_routes
routes_all = EduSpaceMCPServer.execute_tool("get_application_routes", {})
assert "routes" in routes_all
assert routes_all["total"] >= 10
routes_alumno = EduSpaceMCPServer.execute_tool("get_application_routes", {"role": "ALUMNO"})
assert routes_alumno["total"] < routes_all["total"]
assert any("/schedule/today_schedule" in r["path"] for r in routes_alumno["routes"])
# 2. get_canonical_9_steps
steps_result = EduSpaceMCPServer.execute_tool("get_canonical_9_steps", {})
assert "steps" in steps_result
assert steps_result["total"] == 9
assert steps_result["steps"][0]["name"] == "Sedes"
assert steps_result["steps"][8]["name"] == "Reserva de Espacio"
# 3. get_step_guide
guide_aula = EduSpaceMCPServer.execute_tool("get_step_guide", {"action": "crear_aula"})
assert "steps" in guide_aula
assert guide_aula["target_url"] == "/classrooms/list_classrooms"
assert len(guide_aula["steps"]) >= 3
def test_mcp_rest_endpoints():
"""Valida los endpoints REST /api/v1/mcp/tools y /api/v1/mcp/execute."""
client = TestClient(app)
# GET /tools
tools_res = client.get("/api/v1/mcp/tools")
assert tools_res.status_code == 200
assert tools_res.json()["status"] == "success"
# POST /execute válido
exec_res = client.post("/api/v1/mcp/execute", json={
"name": "get_canonical_9_steps",
"arguments": {}
})
assert exec_res.status_code == 200
data = exec_res.json()
assert data["status"] == "success"
assert data["result"]["total"] == 9
# POST /execute inválido
bad_res = client.post("/api/v1/mcp/execute", json={
"name": "herramienta_fantasma"
})
assert bad_res.status_code == 400
def test_mcp_jsonrpc_endpoint():
"""Valida el endpoint estándar JSON-RPC 2.0 /api/v1/mcp."""
client = TestClient(app)
# tools/list
rpc_list = client.post("/api/v1/mcp", json={
"jsonrpc": "2.0",
"id": 1,
"method": "tools/list",
"params": {}
})
assert rpc_list.status_code == 200
res1 = rpc_list.json()
assert res1["jsonrpc"] == "2.0"
assert "tools" in res1["result"]
# tools/call
rpc_call = client.post("/api/v1/mcp", json={
"jsonrpc": "2.0",
"id": 2,
"method": "tools/call",
"params": {
"name": "get_step_guide",
"arguments": {"action": "crear_sede"}
}
})
assert rpc_call.status_code == 200
res2 = rpc_call.json()
assert res2["jsonrpc"] == "2.0"
assert res2["result"]["data"]["target_url"] == "/buildings"
def test_guide_service_intent_detection():
"""Valida que GuideService identifique consultas de acción y construya GuideStepDTO."""
# Crear Aula
step_aula = GuideService.detect_guide_step("¿Cómo creo un aula?", "bedelia")
assert step_aula is not None
assert step_aula.target_url == "/classrooms/list_classrooms"
assert "#btnOpenCreateClassroomModal" in step_aula.selector
# Crear Sede
step_sede = GuideService.detect_guide_step("Quiero crear una sede nueva", "bedelia")
assert step_sede is not None
assert step_sede.target_url == "/buildings"
# Consulta no guiada
step_none = GuideService.detect_guide_step("¿Quién es el decano?", "alumno")
assert step_none is None
def test_chat_endpoint_emits_guide_step_when_requested(init_database):
"""Verifica que el endpoint /api/chat adjunte el guide_step cuando se solicita tutorial."""
client = TestClient(app)
mock_response = MagicMock()
mock_response.status_code = 200
mock_response.json.return_value = {
"choices": [
{
"message": {
"role": "assistant",
"content": "Para crear un aula, presiona el botón Nueva Aula. OPCIONES: [Siguiente paso | Cancelar]"
}
}
]
}
mock_response.raise_for_status = MagicMock()
with patch("httpx.AsyncClient.post", new_callable=AsyncMock) as mock_post:
mock_post.return_value = mock_response
res = client.post("/api/chat", json={
"messages": [{"role": "user", "content": "¿Cómo creo un aula?"}],
"user_role": "bedelia"
})
assert res.status_code == 200
data = res.json()
assert "guide_step" in data
assert data["guide_step"] is not None
assert data["guide_step"]["target_url"] == "/classrooms/list_classrooms"
assert "#btnOpenCreateClassroomModal" in data["guide_step"]["selector"]
assert data["guide_step"]["step_number"] == 1
+1 -1
View File
@@ -1,6 +1,6 @@
{
"name": "frontend",
"version": "3.8.26",
"version": "3.8.27",
"description": "",
"main": "index.js",
"scripts": {
+226
View File
@@ -0,0 +1,226 @@
/**
* walkthrough.css - Estilos del Motor de Asistencia Guiada y Spotlight (SDD-011)
* Compatible con Desktop y Mobile, Modo Claro (UniCABA) y Modo Oscuro.
*/
/* ======================================================== */
/* 1. Backdrop y Máscara de Enfoque */
/* ======================================================== */
.walkthrough-backdrop {
position: fixed;
top: 0;
left: 0;
width: 100vw;
height: 100vh;
background-color: rgba(15, 23, 42, 0.45);
z-index: 1050;
pointer-events: none;
transition: opacity 0.3s ease;
backdrop-filter: blur(2px);
}
/* ======================================================== */
/* 2. Resaltado / Halo Luminoso (Spotlight) */
/* ======================================================== */
.walkthrough-highlight {
position: relative !important;
z-index: 1055 !important;
outline: none !important;
transition: transform 0.25s ease, box-shadow 0.25s ease !important;
animation: pulse-spotlight 1.8s infinite ease-in-out !important;
}
/* Modo Claro: Paleta Institucional UniCABA (Magenta #B43E8E) */
[data-bs-theme="light"] .walkthrough-highlight {
box-shadow: 0 0 0 4px #B43E8E, 0 0 25px rgba(180, 62, 142, 0.55) !important;
border-radius: 8px !important;
}
/* Modo Oscuro: Neón Magenta / Violeta Eléctrico */
[data-bs-theme="dark"] .walkthrough-highlight {
box-shadow: 0 0 0 4px #d946ef, 0 0 30px rgba(217, 70, 239, 0.7) !important;
border-radius: 8px !important;
}
@keyframes pulse-spotlight {
0% {
box-shadow: 0 0 0 3px rgba(180, 62, 142, 0.8), 0 0 15px rgba(180, 62, 142, 0.4);
}
50% {
box-shadow: 0 0 0 7px rgba(217, 70, 239, 0.95), 0 0 35px rgba(217, 70, 239, 0.75);
}
100% {
box-shadow: 0 0 0 3px rgba(180, 62, 142, 0.8), 0 0 15px rgba(180, 62, 142, 0.4);
}
}
/* ======================================================== */
/* 3. Tooltip Flotante de Paso a Paso */
/* ======================================================== */
.walkthrough-tooltip {
position: absolute;
z-index: 1060;
max-width: 320px;
padding: 14px 16px;
border-radius: 14px;
box-shadow: 0 16px 36px rgba(0, 0, 0, 0.25);
font-size: 0.86rem;
animation: fadeInTooltip 0.3s cubic-bezier(0.16, 1, 0.3, 1);
transition: top 0.2s ease, left 0.2s ease;
}
/* Modo Claro */
[data-bs-theme="light"] .walkthrough-tooltip {
background: rgba(255, 255, 255, 0.96);
border: 1.5px solid rgba(180, 62, 142, 0.4);
color: #1e293b;
backdrop-filter: blur(10px);
}
/* Modo Oscuro */
[data-bs-theme="dark"] .walkthrough-tooltip {
background: rgba(30, 41, 59, 0.96);
border: 1.5px solid rgba(217, 70, 239, 0.5);
color: #f8fafc;
backdrop-filter: blur(10px);
}
.walkthrough-tooltip-header {
display: flex;
align-items: center;
justify-content: space-between;
margin-bottom: 8px;
padding-bottom: 6px;
border-bottom: 1px solid rgba(150, 150, 150, 0.2);
}
.walkthrough-badge {
font-size: 0.72rem;
font-weight: 700;
padding: 3px 8px;
border-radius: 12px;
background: linear-gradient(135deg, #B43E8E, #8A256B);
color: #ffffff;
}
.walkthrough-tooltip-body {
line-height: 1.45;
margin-bottom: 12px;
font-weight: 500;
}
.walkthrough-tooltip-footer {
display: flex;
align-items: center;
justify-content: space-between;
gap: 8px;
}
.walkthrough-action-hint {
font-size: 0.75rem;
display: inline-flex;
align-items: center;
gap: 4px;
font-weight: 600;
}
[data-bs-theme="light"] .walkthrough-action-hint {
color: #B43E8E;
}
[data-bs-theme="dark"] .walkthrough-action-hint {
color: #f472b6;
}
/* ======================================================== */
/* 4. Barra Inferior Guía para Dispositivos Móviles */
/* ======================================================== */
.walkthrough-mobile-bar {
position: fixed;
bottom: 0;
left: 0;
right: 0;
z-index: 1065;
padding: 14px 16px;
box-shadow: 0 -8px 24px rgba(0, 0, 0, 0.2);
border-top: 2px solid #B43E8E;
animation: slideUpMobile 0.3s cubic-bezier(0.16, 1, 0.3, 1);
}
[data-bs-theme="light"] .walkthrough-mobile-bar {
background-color: #ffffff;
color: #1e293b;
}
[data-bs-theme="dark"] .walkthrough-mobile-bar {
background-color: #0f172a;
color: #f8fafc;
border-top-color: #d946ef;
}
.walkthrough-btn-action {
min-height: 44px;
font-weight: 600;
font-size: 0.88rem;
border-radius: 10px;
display: inline-flex;
align-items: center;
justify-content: center;
gap: 6px;
padding: 8px 16px;
}
/* ======================================================== */
/* 5. Banner de Redirección hacia Pantalla de Guía */
/* ======================================================== */
.walkthrough-redirect-banner {
position: fixed;
top: 70px;
left: 50%;
transform: translateX(-50%);
z-index: 1070;
min-width: 300px;
max-width: 90vw;
padding: 12px 18px;
border-radius: 12px;
box-shadow: 0 10px 30px rgba(0, 0, 0, 0.25);
display: flex;
align-items: center;
justify-content: space-between;
gap: 12px;
animation: fadeInTooltip 0.3s ease;
}
[data-bs-theme="light"] .walkthrough-redirect-banner {
background-color: #ffffff;
border: 1.5px solid #B43E8E;
color: #1e293b;
}
[data-bs-theme="dark"] .walkthrough-redirect-banner {
background-color: #1e293b;
border: 1.5px solid #d946ef;
color: #ffffff;
}
/* ======================================================== */
/* 6. Animaciones Suaves */
/* ======================================================== */
@keyframes fadeInTooltip {
from {
opacity: 0;
transform: translateY(6px);
}
to {
opacity: 1;
transform: translateY(0);
}
}
@keyframes slideUpMobile {
from {
transform: translateY(100%);
}
to {
transform: translateY(0);
}
}
+13
View File
@@ -201,6 +201,19 @@
const data = await res.json();
if (res.ok && data.response) {
appendMessage('assistant', data.response, data.quick_options || [], true);
// Si UdeCi emite una directiva de guía interactiva, activar el Spotlight
if (data.guide_step && window.WalkthroughEngine) {
const panel = document.getElementById('aiChatPanel');
const launcher = document.getElementById('aiChatLauncher');
if (panel && launcher) {
panel.classList.add('d-none');
launcher.style.transform = '';
}
setTimeout(() => {
window.WalkthroughEngine.startStep(data.guide_step);
}, 250);
}
} else {
const errorMsg = data.detail || data.message || 'UdeCi no pudo procesar la respuesta en este momento.';
appendMessage('assistant', `⚠️ ${errorMsg}`, [], false);
+252
View File
@@ -0,0 +1,252 @@
/**
* walkthrough-engine.js - Motor de Asistencia Interactiva y Spotlight para UdeCi (SDD-011)
* "Enseñar a pescar, no dar el pescado". Ilumina elementos en vivo, guía al usuario
* y aguarda a que sea él quien ejecute la acción.
*/
(function() {
'use strict';
const PENDING_STEP_KEY = 'edu_space_walkthrough_pending_step';
let currentStepData = null;
let activeHighlightEl = null;
let backdropEl = null;
let tooltipEl = null;
let mobileBarEl = null;
let redirectBannerEl = null;
function isMobile() {
return window.innerWidth < 768;
}
function removeElement(el) {
if (el && el.parentNode) {
el.parentNode.removeChild(el);
}
}
function clearSpotlight() {
if (activeHighlightEl) {
activeHighlightEl.classList.remove('walkthrough-highlight');
activeHighlightEl = null;
}
removeElement(backdropEl);
backdropEl = null;
removeElement(tooltipEl);
tooltipEl = null;
removeElement(mobileBarEl);
mobileBarEl = null;
removeElement(redirectBannerEl);
redirectBannerEl = null;
currentStepData = null;
}
function createBackdrop() {
if (backdropEl) return backdropEl;
backdropEl = document.createElement('div');
backdropEl.className = 'walkthrough-backdrop';
document.body.appendChild(backdropEl);
return backdropEl;
}
function showRedirectBanner(targetUrl, stepMessage) {
clearSpotlight();
redirectBannerEl = document.createElement('div');
redirectBannerEl.className = 'walkthrough-redirect-banner';
redirectBannerEl.innerHTML = `
<div class="d-flex align-items-center gap-2">
<span class="badge bg-primary rounded-pill px-2 py-1"><i class="bi bi-compass"></i> Guía UdeCi</span>
<span class="small fw-semibold">Debemos ir a la pantalla correspondiente para continuar.</span>
</div>
<div class="d-flex align-items-center gap-2">
<button type="button" class="btn btn-sm btn-primary walkthrough-btn-action" id="walkthroughGoBtn">
Ir a la pantalla <i class="bi bi-arrow-right"></i>
</button>
<button type="button" class="btn btn-sm btn-outline-secondary border-0" id="walkthroughCancelRedirectBtn" title="Cancelar">
<i class="bi bi-x-lg"></i>
</button>
</div>
`;
document.body.appendChild(redirectBannerEl);
document.getElementById('walkthroughGoBtn').addEventListener('click', () => {
sessionStorage.setItem(PENDING_STEP_KEY, JSON.stringify(currentStepData));
window.location.href = targetUrl;
});
document.getElementById('walkthroughCancelRedirectBtn').addEventListener('click', () => {
clearSpotlight();
sessionStorage.removeItem(PENDING_STEP_KEY);
});
}
function positionTooltip(targetEl, tooltip) {
const rect = targetEl.getBoundingClientRect();
const tooltipWidth = 320;
const margin = 12;
let top = rect.bottom + window.scrollY + margin;
let left = rect.left + window.scrollX;
// Ajuste si se sale a la derecha
if (left + tooltipWidth > window.innerWidth - 20) {
left = window.innerWidth - tooltipWidth - 20;
}
if (left < 10) left = 10;
// Si se sale por abajo de la pantalla, posicionar arriba del elemento
if (rect.bottom + 180 > window.innerHeight) {
top = rect.top + window.scrollY - 160;
}
tooltip.style.top = `${Math.max(10, top)}px`;
tooltip.style.left = `${left}px`;
}
function renderTooltipDesktop(targetEl, step) {
removeElement(tooltipEl);
tooltipEl = document.createElement('div');
tooltipEl.className = 'walkthrough-tooltip';
tooltipEl.innerHTML = `
<div class="walkthrough-tooltip-header">
<span class="walkthrough-badge">UdeCi · Paso ${step.step_number} de ${step.total_steps}</span>
<button type="button" class="btn-close btn-close-white btn-sm" id="walkthroughCloseBtn" aria-label="Cerrar"></button>
</div>
<div class="walkthrough-tooltip-body">
${step.message}
</div>
<div class="walkthrough-tooltip-footer">
<span class="walkthrough-action-hint">
<i class="bi bi-hand-index-thumb"></i> Haz clic en el botón iluminado
</span>
<button type="button" class="btn btn-sm btn-outline-secondary py-0 px-2" style="font-size: 0.75rem;" id="walkthroughSkipBtn">
Omitir
</button>
</div>
`;
document.body.appendChild(tooltipEl);
positionTooltip(targetEl, tooltipEl);
document.getElementById('walkthroughCloseBtn').addEventListener('click', clearSpotlight);
document.getElementById('walkthroughSkipBtn').addEventListener('click', clearSpotlight);
}
function renderMobileBar(step) {
removeElement(mobileBarEl);
mobileBarEl = document.createElement('div');
mobileBarEl.className = 'walkthrough-mobile-bar';
mobileBarEl.innerHTML = `
<div class="d-flex align-items-center justify-content-between mb-2">
<span class="badge bg-primary">UdeCi · Paso ${step.step_number}/${step.total_steps}</span>
<button type="button" class="btn btn-sm btn-outline-light border-0 py-0" id="walkthroughMobileClose">
<i class="bi bi-x-lg"></i>
</button>
</div>
<div class="small fw-semibold mb-2">
${step.message}
</div>
<div class="d-flex align-items-center justify-content-between">
<span class="small text-muted"><i class="bi bi-hand-index"></i> Presiona el elemento iluminado</span>
<button type="button" class="btn btn-sm btn-outline-secondary" id="walkthroughMobileSkip">Omitir</button>
</div>
`;
document.body.appendChild(mobileBarEl);
document.getElementById('walkthroughMobileClose').addEventListener('click', clearSpotlight);
document.getElementById('walkthroughMobileSkip').addEventListener('click', clearSpotlight);
}
function highlightElement(el, step) {
clearSpotlight();
currentStepData = step;
activeHighlightEl = el;
createBackdrop();
el.classList.add('walkthrough-highlight');
// Scroll suave hacia el elemento
el.scrollIntoView({ behavior: 'smooth', block: 'center' });
if (isMobile()) {
renderMobileBar(step);
} else {
renderTooltipDesktop(el, step);
}
// Listener para detectar la interacción del usuario
const handleUserAction = function() {
// Micro-feedback de éxito
if (activeHighlightEl) {
activeHighlightEl.style.transition = 'all 0.3s ease';
activeHighlightEl.style.transform = 'scale(1.05)';
}
setTimeout(() => {
clearSpotlight();
sessionStorage.removeItem(PENDING_STEP_KEY);
}, 500);
el.removeEventListener('click', handleUserAction);
};
el.addEventListener('click', handleUserAction, { once: true });
}
function startStep(step) {
if (!step || !step.selector) return;
currentStepData = step;
const currentPath = window.location.pathname;
const targetPath = step.target_url;
// Si el usuario está en otra pantalla, sugerir redirección
if (targetPath && !currentPath.includes(targetPath) && !targetPath.includes(currentPath)) {
showRedirectBanner(targetPath, step.message);
return;
}
// Si ya estamos en la pantalla, buscar selector
let targetEl = document.querySelector(step.selector);
// Si no lo encuentra de inmediato (por modales o carga diferida), reintentar brevemente
if (!targetEl) {
let attempts = 0;
const timer = setInterval(() => {
attempts++;
targetEl = document.querySelector(step.selector);
if (targetEl) {
clearInterval(timer);
highlightElement(targetEl, step);
} else if (attempts >= 8) {
clearInterval(timer);
console.warn(`[WalkthroughEngine] Elemento no encontrado: ${step.selector}`);
}
}, 250);
} else {
highlightElement(targetEl, step);
}
}
function checkPendingStep() {
try {
const raw = sessionStorage.getItem(PENDING_STEP_KEY);
if (raw) {
const step = JSON.parse(raw);
sessionStorage.removeItem(PENDING_STEP_KEY);
setTimeout(() => {
startStep(step);
}, 400);
}
} catch (e) {}
}
// Exponer API global
window.WalkthroughEngine = {
startStep,
clearSpotlight,
checkPendingStep
};
if (document.readyState === 'loading') {
document.addEventListener('DOMContentLoaded', checkPendingStep);
} else {
checkPendingStep();
}
})();
+3 -3
View File
@@ -86,9 +86,9 @@ const env = nunjucks.configure(path.join(__dirname, '../views'), {
});
// Versiones institucionales del sistema
const APP_VERSION = '3.8.26';
const FRONTEND_VERSION = '3.8.26';
const BACKEND_VERSION = '3.8.26';
const APP_VERSION = '3.8.27';
const FRONTEND_VERSION = '3.8.27';
const BACKEND_VERSION = '3.8.27';
env.addGlobal('app_version', APP_VERSION);
env.addGlobal('frontend_version', FRONTEND_VERSION);
+2
View File
@@ -29,6 +29,7 @@
<!-- Design System & Custom Theme -->
<link href="/css/theme.css" rel="stylesheet">
<link href="/css/style.css" rel="stylesheet">
<link href="/css/walkthrough.css" rel="stylesheet">
<style>
body {
font-family: 'Inter', sans-serif;
@@ -1780,6 +1781,7 @@
});
</script>
<script src="/js/walkthrough-engine.js"></script>
{% if auth_user and auth_user.is_authenticated %}
{% include "partials/ai_chat_widget.html" %}
{% endif %}
@@ -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.