SREQ-UX-04 · Tour guiado de Alertas de Stock y filtros en una fila
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
| # | Anclaje | Qué explica |
|---|---|---|
| 1 | alertas-stock.contenido | La pantalla y el origen de las cifras (stock por bodega y stock de seguridad) |
| 2 | alertas-stock.titulo | El título y su convivencia con las pestañas de trabajo |
| 3 | alertas-stock.subtitulo | Que no es un reporte histórico sino la lista del día |
| 4 | alertas-stock.boton.estadisticas | El ojo: pliega las tarjetas y guarda la preferencia |
| 5 | alertas-stock.boton.exportar | CSV de lo filtrado, con nombre y columnas, y por qué se deshabilita |
| 6 | alertas-stock.boton.ayuda | El (?): repite el recorrido |
| 7-11 | alertas-stock.estadisticas, .metrica.total, .alta, .sin-stock, .bajo | El bloque de resumen y una tarjeta por paso, con su icono, su color y la regla que la alimenta |
| 12 | alertas-stock.filtros | Que título y campos comparten una fila y no hay botón «Aplicar» |
| 13 | alertas-stock.filtros.titulo | El embudo y la palabra «Filtros» dentro de la fila |
| 14 | alertas-stock.filtros.buscar | Texto libre contra producto, mensaje, categoría y proveedor |
| 15 | alertas-stock.filtros.buscar.icono | La lupa: dentro del campo y sin función de botón |
| 16 | alertas-stock.filtros.tipo | Las cinco clases de alerta, incluida «Bajo Seguridad (INV-007)» |
| 17 | alertas-stock.filtros.prioridad | Alta, media y baja, combinables con el tipo |
| 18 | alertas-stock.filtros.fecha-inicio | Rango por vencimiento desde las 00:00 |
| 19 | alertas-stock.filtros.fecha-fin | Rango hasta las 23:59 |
| 20 | alertas-stock.lista | La card del listado |
| 21 | alertas-stock.lista.titulo | «Alertas Activas» y su triángulo ámbar |
| 22 | alertas-stock.lista.contador | «Cargando alertas…» / «N alertas encontradas» |
| 23-37 | alertas-stock.alerta… y .paginacion | Anatomía de la alerta y paginación (ver abajo) |
Anatomía de la alerta (solo si hay resultados)
| Anclaje | Qué explica |
|---|---|
alertas-stock.alerta | Las dos zonas de la tarjeta |
alertas-stock.alerta.icono | Flecha, triángulo, círculo o calendario según el tipo |
alertas-stock.alerta.producto | Producto + presentación + categoría |
alertas-stock.alerta.mensaje | El texto con las cifras del motivo |
alertas-stock.alerta.ubicacion | Marcador: ruta física (solo si existe) |
alertas-stock.alerta.badges | La fila de etiquetas |
alertas-stock.alerta.badge.prioridad | Colores rojo / amarillo / azul |
alertas-stock.alerta.badge.tipo | El tipo traducido a texto |
alertas-stock.alerta.badge.categoria | Categoría (solo si existe) |
alertas-stock.alerta.badge.almacen | Bodega del faltante (solo si existe) |
alertas-stock.alerta.stock | La columna de cifras |
alertas-stock.alerta.stock.actual | Existencia hoy |
alertas-stock.alerta.stock.minimo | Umbral de reposición |
alertas-stock.alerta.stock.seguridad | Colchón consumido, en rojo (solo si > 0) |
alertas-stock.paginacion | Anterior/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(?)conuseTourOpcional; card de filtros en una fila; filtrado por rango de vencimiento;aria-label/aria-presseden el ojo yaria-hiddenen los iconos decorativos.src/config/tours.ts—pasosAlertasStock(estado)con 37 pasos y el móduloalertas-stockactivo (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 entours.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» usabatoast.info, que no existe en eluseToastde shadcn; pasa atoast({ title })(eltscno 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 --noEmitlimpio.
📄 Requerimiento: SREQ-UX-04: Tour guiado por funcionalidad
