Files

4.1 KiB

Desglose de Tareas: Servidor MCP y Asistente Interactivo Guiado (SDD-011)

Tareas de Implementación

  • 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.
  • 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.
  • 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.
  • 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.
  • 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).
  • 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.