Saltar al contenido principal

SREQ-UX-04 · Tour guiado por funcionalidad

· 3 min de lectura
Yovany Suárez Silva
Software Engineer - FullStack Developer

El requerimiento pedía un tour guiado en cada funcionalidad principal, siguiendo los patrones de SurosV4 en el sistema web y de sean-pets en la app móvil. La foto de partida era curiosa: el medio que parecía «secundario» ya lo tenía todo, y el principal no tenía nada.

MedioAntes
Web (ccf-almacen-web)Ningún tour. Solo un botón de ayuda contextual (UX-006) y marcadores data-tour dormidos en el login
Móvil (ccf-almacen-mb)Tour completo (motor, guion, anclas, store), pero 3 pantallas sin guía

🧭 El motor, portado de SurosV4​

SurosV4 resuelve el tour con un único tour.js global: un recorte oscuro sobre el elemento objetivo y una burbuja con «n / m» y Anterior/Siguiente/Finalizar. En el web de CCF se portó a un componente React —sin librerías externas, porque la CSP del proyecto es script-src 'self'— y se separó en tres piezas, igual que en el móvil:

PiezaQué hace
GuidedTour (motor)Recorte, burbuja, medición, teclado y accesibilidad. No conoce el contenido
src/config/tours.ts (datos)El guion: un recorrido por módulo
TourProvider / TourHost (orquestación)Estado, persistencia y auto-arranque

Dos mejoras sobre la referencia: el motor es declarativo (estado de React, no DOM a mano) y un paso cuyo objetivo no aparece se muestra centrado como texto, en vez de saltarse en silencio.

🎯 Un tour por funcionalidad​

Cada módulo marca su contenedor con data-tour-modulo y sus elementos con data-tour="modulo.algo" (la misma convención de los data-tour que ya había en el login). La cabecera del dashboard gana un botón (?) que lanza el recorrido del módulo abierto, y Inicio se explica solo la primera vez que cada usuario entra.

Se cubren ~20 módulos de primer nivel: desde Inicio y Solicitudes hasta Firma electrónica, Sesiones, Jobs o IPs y bloqueos.

📱 El móvil: cerrar los vacíos​

El terminal ya seguía el patrón de sean-pets. Solo faltaba instrumentar detalle de producto, cambio de contraseña y configuración de notificaciones: anclas para poder resaltarlas, sus pasos y el botón (?) en su cabecera. Los pasos nuevos son «de pantalla» (no entran en el recorrido de bienvenida) y no navegan, para no perder los parámetros de ruta del detalle.

✅ Verificación​

  • Web: tsc --noEmit en 0; la suite de tours pasa 5/5 con un chequeo cruzado que exige que todo selector de un guion exista como data-tour en el código (un selector sin objetivo es un paso ciego). Sin regresiones: los fallos que quedan son los previos de la migración TEC-019.
  • Móvil: tsc --noEmit en 0 y 85/85 pruebas.
  • Pendiente una revisión visual de cada tour sobre su pantalla: este entorno no tiene el stack levantado.

📄 Documento del requerimiento: SREQ-UX-04: Tour guiado por funcionalidad.