Saltar al contenido principal

SREQ-UX-04 · Tour guiado de Alertas de Stock y filtros en una fila

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

Alertas de Stock es la lista de trabajo diaria del almacén: lo que se agotó, lo que está por debajo del mínimo y lo que ya consumió el stock de seguridad. Ahora tiene tour guiado al detalle, lanzado desde el botón (?) de la cabecera, y su card de «Filtros» deja de ocupar una cabecera completa para vivir en una sola fila, con el título dentro.

🧭 Treinta y siete pasos, todos condicionados a lo que hay en pantalla​

#AnclajeQué explica
1alertas-stock.contenidoLa pantalla y el origen de las cifras (stock por bodega y stock de seguridad)
2alertas-stock.tituloEl título y su convivencia con las pestañas de trabajo
3alertas-stock.subtituloQue no es un reporte histórico sino la lista del día
4alertas-stock.boton.estadisticasEl ojo: pliega las tarjetas y guarda la preferencia
5alertas-stock.boton.exportarCSV de lo filtrado, con nombre y columnas, y por qué se deshabilita
6alertas-stock.boton.ayudaEl (?): repite el recorrido
7-11alertas-stock.estadisticas, .metrica.total, .alta, .sin-stock, .bajoEl bloque de resumen y una tarjeta por paso, con su icono, su color y la regla que la alimenta
12alertas-stock.filtrosQue título y campos comparten una fila y no hay botón «Aplicar»
13alertas-stock.filtros.tituloEl embudo y la palabra «Filtros» dentro de la fila
14alertas-stock.filtros.buscarTexto libre contra producto, mensaje, categoría y proveedor
15alertas-stock.filtros.buscar.iconoLa lupa: dentro del campo y sin función de botón
16alertas-stock.filtros.tipoLas cinco clases de alerta, incluida «Bajo Seguridad (INV-007)»
17alertas-stock.filtros.prioridadAlta, media y baja, combinables con el tipo
18alertas-stock.filtros.fecha-inicioRango por vencimiento desde las 00:00
19alertas-stock.filtros.fecha-finRango hasta las 23:59
20alertas-stock.listaLa card del listado
21alertas-stock.lista.titulo«Alertas Activas» y su triángulo ámbar
22alertas-stock.lista.contador«Cargando alertas…» / «N alertas encontradas»
23-37alertas-stock.alerta… y .paginacionAnatomía de la alerta y paginación (ver abajo)

Anatomía de la alerta (solo si hay resultados)​

AnclajeQué explica
alertas-stock.alertaLas dos zonas de la tarjeta
alertas-stock.alerta.iconoFlecha, triángulo, círculo o calendario según el tipo
alertas-stock.alerta.productoProducto + presentación + categoría
alertas-stock.alerta.mensajeEl texto con las cifras del motivo
alertas-stock.alerta.ubicacionMarcador: ruta física (solo si existe)
alertas-stock.alerta.badgesLa fila de etiquetas
alertas-stock.alerta.badge.prioridadColores rojo / amarillo / azul
alertas-stock.alerta.badge.tipoEl tipo traducido a texto
alertas-stock.alerta.badge.categoriaCategoría (solo si existe)
alertas-stock.alerta.badge.almacenBodega del faltante (solo si existe)
alertas-stock.alerta.stockLa columna de cifras
alertas-stock.alerta.stock.actualExistencia hoy
alertas-stock.alerta.stock.minimoUmbral de reposición
alertas-stock.alerta.stock.seguridadColchón consumido, en rojo (solo si > 0)
alertas-stock.paginacionAnterior/siguiente, números, tamaño de página y total

Sin alertas, los quince pasos de anatomía se sustituyen por el estado vacío (alertas-stock.lista.vacio) y el recorrido queda en 23 pasos. Si la primera alerta no trae ubicación, categoría, bodega o seguridad, esos pasos no se incluyen. Al lanzar el tour se muestran las tarjetas si estaban ocultas, porque el guion las explica.

🧱 La card de filtros, en una sola fila​

Antes: CardHeader con icono, «Filtros» y descripción, y debajo una rejilla de cinco campos. Ahora un único CardContent con un contenedor flex flex-wrap items-end: el título es el primer ítem y los cinco campos lo acompañan con flex-1 y anchos mínimos. Se gana la altura de la cabecera y todo queda a la vista de un vistazo; en pantallas estrechas la fila se pliega sin romper etiquetas.

La descripción («Filtra las alertas por diferentes criterios») se conserva como texto para lectores de pantalla, sin ocupar una línea visual.

🐞 Las fechas ahora filtran de verdad​

fechaInicio y fechaFin estaban en el estado y se pintaban, pero filterAlerts nunca los usaba: elegir un rango no cambiaba nada. Ahora se aplican sobre la única fecha que trae una alerta, fechaVencimiento, tomando el día completo en ambos extremos. Con un rango activo, las alertas sin fecha de vencimiento quedan fuera, porque no hay forma de ubicarlas.

🛠️ Cambios​

  • src/pages/stock-alerts.tsx — data-tour-modulo="alertas-stock", anclajes de sección, campo, icono y botón; botón (?) con useTourOpcional; card de filtros en una fila; filtrado por rango de vencimiento; aria-label/aria-pressed en el ojo y aria-hidden en los iconos decorativos.
  • src/config/tours.ts — pasosAlertasStock(estado) con 37 pasos y el módulo alertas-stock activo (MODULOS_CON_TOUR_ACTIVO).
  • src/config/tours.spec.ts — lista canónica de módulos activos y composición del guion.
  • src/components/__tests__/alertas-stock-tour.test.tsx (nuevo) — fila única de filtros, anclajes en el DOM, (?) lanzando el recorrido («1 / 37»), estado vacío («1 / 23») y el rango de fechas acotando el listado.
  • src/components/__tests__/tour-host.test.tsx — la lista de módulos activos se valida en tours.spec.ts; aquí se comprueba que los recorridos usados estén activos (deja de romperse cada vez que se activa una pantalla nueva).
  • src/components/ubicaciones/ubicaciones-management.tsx — el aviso de «tour no disponible» usaba toast.info, que no existe en el useToast de shadcn; pasa a toast({ title }) (el tsc no compilaba por esta línea).

✅ Verificación​

  • alertas-stock-tour.test.tsx: 5 pruebas en verde.
  • tours.spec.ts: 14 pruebas en verde (chequeo cruzado de los 37 anclajes activos).
  • tsc --noEmit limpio.

📄 Requerimiento: SREQ-UX-04: Tour guiado por funcionalidad