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
+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();
}
})();