""" 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