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
@@ -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.