Files
admin-edu-space/backend/app/services/guide_service.py
T

138 lines
5.6 KiB
Python

"""
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",
current_path: Optional[str] = None
) -> Optional[GuideStepDTO]:
"""
Analiza la consulta del usuario y el contexto de la pantalla activa
para retornar el paso interactivo más relevante de la UI.
"""
if not query:
return None
q = _normalize(query)
path = (current_path or "").lower()
# Acción 1: Crear / Dar de alta Sede o Edificio
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 or "agregar" in q):
guide = STEP_GUIDES["crear_sede"]
if "add_building" in path or ("building" in path and "add" in path):
step = guide["steps"][1]
return GuideStepDTO(
target_url="/buildings/add_building",
selector=step["selector"],
message=step["message"],
expected_action=step["expected_action"],
step_number=2,
total_steps=len(guide["steps"])
)
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 2: Crear / Agregar 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 or "agregar" in q):
guide = STEP_GUIDES["crear_aula"]
if "add_classroom" in path:
step = guide["steps"][1]
return GuideStepDTO(
target_url="/classrooms/add_classroom",
selector=step["selector"],
message=step["message"],
expected_action=step["expected_action"],
step_number=2,
total_steps=len(guide["steps"])
)
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 3: 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 or "agregar" 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 4: Consultar Cursada de Hoy (Alumnos / Docentes / Bedelía)
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 or "cartelera" 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"])
)
# Acción 5: Gradebook / Calificaciones (Docente / Alumno)
if ("gradebook" in q or "calificacion" in q or "calificaciones" in q or "notas" in q or "acta" in q or "regularidad" in q):
guide = STEP_GUIDES["gradebook"]
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 6: Importador de Google Sheets
if ("sheet" in q or "sheets" in q or "importar" in q or "sincronizar" in q):
guide = STEP_GUIDES["importar_sheets"]
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