Release — Mejoras de UX, sockets y documentación (Agosto 2026)
· 17 min de lectura
Resumen de los cambios implementados en esta entrega. Todos quedan reflejados en esta wiki como parte de la regla de documentación obligatoria.
🔢 Auto-generación de código único en productos
- Backend (
ccf-almacen-api): el campocodigoenCreateProductoDtoahora es opcional. Si viene vacío,ProductosService.create()lo genera automáticamente con el formato{3 letras de categoría}-{idProducto pad 3}(ej.PAP-001). Si viene un código manual, se respeta y se valida su unicidad.update()también regenera cuando el código llega vacío o con el sentinel'...'. - Frontend (
ccf-almacen-web): el formulario de producto informa que el código único se genera automáticamente si el campo queda vacío.
🔌 Fix de sockets del panel lateral derecho
- Backend:
handleConnectioncon try/catch (ya no aborta el handshake si falla la BD); nuevo método livianoUsuariosService.findLogeado(); nuevo eventorequest-status-updatedemitido en aprobar/rechazar/cambiar estado/actualizar solicitudes; logout ahora emiteusers-update. - Frontend: el socket compartido se reconecta automáticamente cuando la sonda de salud corrige la URL base; el logout cierra el socket; el panel "Usuarios en línea" muestra estado de conexión y usa el campo correcto
logeado.
🚀 Despliegue
- Consolidado
next.config.mjsennext.config.js(se eliminó el duplicado; se preservaron losimages.remotePatternsnecesarios paraavatars.githubusercontent.com). - Actualizado
CLIENT_SOCKETen el.envdel API al host real de producción.
🏷️ Patrón visual: badges robustos
- Componente base
badge.tsxcon más padding (px-3 py-1.5) → aplica a todos los badges de la app. - Badges custom de Solicitudes y otros módulos alineados al patrón.
ℹ️ Infografía en labels de formularios
- Nuevo componente
FormLabelWithInfo(tooltip ℹ️) aplicado a los formularios principales: Producto, Solicitud, Solicitud Móvil, Usuario, Perfil y Login (que ya lo tenía).
🎨 Íconos contextuales
- Labels: ícono contextual al inicio de cada label (ej.
Packagepara producto,Lockpara contraseña) + tooltip ℹ️ al final. - Títulos: íconos en títulos de formularios, listas y detalles (Producto, Solicitud, Despacho, Oficina, Inventario, Dashboard, Notificaciones).
🔔 Notificaciones del sistema: fondo verde suave e iconos
- Causa raíz: la gran mayoría de notificaciones (productos, solicitudes, oficinas, usuarios, stock) usa el hook shadcn
useToast, que renderiza en elToasterdesrc/registry/new-york/ui/toaster.tsx. Ese componente salía sin iconos y en blanco/negro (bg-background text-foreground) y sindata-type, por lo que los estilos detoast-improvements.css(.toast[data-type=...]) nunca aplicaban. Solo una minoría usa Sonner directo. - Solución (toaster shadcn):
ui/toaster.tsxahora resuelve el tono semántico del toast (data-typesi existe →variant: destructive→error→ si no,default) y renderiza:- Icono contextual (lucide-react):
CheckCircle2(éxito),Info(info),BellRing(default/sistema),AlertTriangle(advertencia),XCircle(error). - Fondo verde suave con paleta institucional (light:
green-50/green-200/green-800; dark:green-950/green-900/green-100) para success/info/default; ámbar suave para warning; rojo suave para error (patrón semáforo conservado).
- Icono contextual (lucide-react):
- Solución (Sonner): se eliminó el fondo blanco forzado del
SonnerToasterensidebar.tsx(toastOptions.style) y se sobrescribieron las variables CSS de Sonner ensrc/styles/toast-improvements.csscon la misma paleta verde. - Archivos:
src/registry/new-york/ui/toaster.tsx,src/components/layouts/sidebar/sidebar.tsx,src/styles/toast-improvements.css.
🔢 Visibilidad del input "Cantidad a entregar" en Despacho de solicitud
- En
request-dispatch.tsx(tabla "Productos a Despachar"), el input de cantidad tenía solow-20con el borde tenue por defecto de shadcn → se perdía entre la fila. - Ahora el input tiene:
w-24, texto centrado y seminegrita, bordeborder-2gris visible (border-gray-400), fondobg-gray-50con sombra,hover:border-gray-500y foco verde institucional (focus:border-green-500 focus:ring-green-500/30). Los estados de completado (verdebg-green-50) y error (rojobg-red-50) se mantienen y siguen teniendo prioridad.
💬 Tooltips informativos en botones de gestión de solicitud
- En
request-detail.tsx, los botones de acción de estado (Aprobar, Rechazar, Iniciar proceso de despacho, Completar) ahora muestran un tooltip (react-tooltipidmy-tooltip-t, ya montado enauth-provider.tsx) con una descripción clara del efecto de la acción antes de hacer clic. - Textos por acción en el mapa
ACTION_TOOLTIPS(constante del componente): aprobada, rechazada, en_proceso y completada; fallback genérico si llega una acción sin texto.
⚠️ Ventanas de confirmación (pausa de validación) en acciones de proceso
- Despacho (
request-dispatch.tsx): el botón "Confirmar Despacho" ya no ejecuta directamente. Abre unAlertDialog(patrón shadcn ya usado en eliminaciones) que resume el proceso: unidades y productos a entregar, estado resultante ("Completada" o "En proceso"), actualización de detalles y registro de movimientos de inventario con descuento de stock. Confirmar (verde) ejecuta; Cancelar cierra. - Gestión de solicitud (
request-detail.tsx): los botones Aprobar / Rechazar / Iniciar proceso de despacho / Completar ahora pasan por un diálogo de confirmación que explica el efecto de la acción (reutilizaACTION_TOOLTIPScomo descripción) antes de cambiar el estado. - Patrón:
AlertDialogdesrc/registry/new-york/ui/alert-dialog.tsx(Radix), botón de acción con color semántico (rojo para rechazar, verde para el resto).
Auditoría de confirmaciones (validación de usuario donde es necesaria)
Se revisaron los botones que accionan procesos irreversibles o sensibles:
Agregado en esta revisión:
stock-loading.tsx: botón "Cargar Inventario" (resumen de productos/unidades y movimientos de entrada) y "Limpiar Lista" (descarta la selección).request-detail-standalone.tsx: botón "Aprobar" (la vista standalone no tenía confirmación).product-image-upload.tsx: eliminar la imagen persistida del producto (botón X sobre la preview; si es imagen nueva sin persistir, elimina directo sin diálogo).
Ya tenían confirmación (verificado, sin cambios):
- Eliminar producto (
products.tsx), eliminar solicitud y motivo de rechazo (solicitudes/page.tsx), eliminar usuario (data-page.tsx), remover usuario de oficina (office-management.tsx).
No requieren confirmación (justificado):
- Abrir la pantalla de despacho (la confirmación ocurre al confirmar el despacho), quitar filas en formularios (edición local antes de enviar), exportar PDF/XLS, marcar notificaciones leídas, limpiar filtros de búsqueda, crear solicitud de reposición, logout.
⏳ LoadingIndicator: secuencia animada en todos los loadings de carga
- Nuevo componente
src/components/common/loading-indicator.tsx+src/styles/loading-indicator.css: anillo con track + arco giratorio (verde institucional, glow), núcleo pulsante, y puntos secuenciales junto al texto (secuencia estilo "cargando…"). Accesible (role="status",aria-live="polite") y respetaprefers-reduced-motion. Variantessm/md/lgylabelopcional. LoadingState(data-states.tsx) ahora usa el componente (beneficia aproduct-listy futuros usos).- Reemplazados todos los spinners HTML estáticos (
animate-spin rounded-full border-b-2) de páginas porLoadingIndicator: mobile-request-new, mobile-request-detail ([id]y componente), stock-alerts (x2), product-detail, request-detail-standalone, warehouse-reports, reports-charts, user/table, user-page, mobile-requests, inventory-summary, inventory-movement-list, office-management. - Botones de submit unificados al patrón
Loader2(lucide, animado): product-form, user-form.
📐 Formulario de solicitudes: campos distribuidos al ancho del contenedor
- En
request-form.tsx(crear/editar solicitudes), los campos del grid "Información de la Solicitud" tenían anchos fijos que rompían la distribución:- "Área origen de solicitud":
w-[300px]fijo → ahoraw-full min-w-0(ocupa su columna del grid de 4). - "Tipo de Solicitud":
max-w-[120px] ml-12(diminuto) → ahoraw-full min-w-0(sin margen artificial). - "Prioridad":
max-w-[120px](diminuto) → ahoraw-full min-w-0.
- "Área origen de solicitud":
- Resultado: los
Selectocupan el ancho de su columna dentro del gridmd:grid-cols-4, distribuyéndose a todo el ancho del contenedor padre.
📝 Título correcto al crear vs editar solicitud
- En
request-form.tsx, el título mostraba "Editar Solicitud" incluso al crear, porquesolicitudes/page.tsxpasa uninitialDatacon valores por defecto (sinidSolicitud) también en modo CREATE (el condicionalinitialData ? "Editar" : "Nueva"era truthy). - Ahora usa el mismo criterio que
onSubmitFormpara distinguir modos:initialData?.idSolicitud ? "Editar Solicitud" : "Creando nueva solicitud".
🎨 Integración visual de formularios (solicitudes ↔ productos)
- Ancho unificado (ancho máximo de solicitudes):
product-form.tsxperdió elmax-w-4xl mx-auto→ ahora el formulario de producto usaw-fullcomo el de solicitudes (ocupa el ancho del contenedor). - Patrón de card contenedora (del producto → solicitudes): ambas cards de
request-form.tsx("Información de la Solicitud" y "Elementos Solicitados") ahora usan el patrón del producto:w-full border-blue-100 bg-gradient-to-br from-blue-50/70 via-white to-indigo-50/60 shadow-sm. - Colores de notas (del producto → solicitudes): notas de ayuda en cajita azul (
border-blue-200 bg-blue-50 text-blue-800) víaFormDescriptionen Propósito, Descripción y Cantidad; banner informativo azul/índigo al inicio de "Elementos Solicitados" (patrón del banner "Generar SKU automáticamente" del producto).
🔄 Recarga de la lista de solicitudes tras despachar
- Bug: tras "Confirmar Despacho", la lista de Solicitudes volvía sin recargar:
onDispatchCompletesolo hacíasetViewState(LIST)(sinfetchRequests()), a diferencia de los flujos de eliminar/guardar/cambiar estado. El botón "Refrescar" tampoco recargaba porquehandleRefreshsolo reseteaba estados que, sin búsqueda activa, no cambiaban (React no re-renderizaba y no había refetch). - Fix en
solicitudes/page.tsx:onDispatchCompleteahora hacesetViewState(LIST)+fetchRequests()(igual que los demás flujos);onBack(volver/cancelar del despacho) también refresca la lista por si hubo despacho parcial o cambios de estado; se pasaonRefresh={fetchRequests}aRequestList. - Fix en
request-list.tsx: nueva prop opcionalonRefresh; el botón "Refrescar" la invoca para forzar el refetch real desde la API (además de resetear búsqueda/orden). - Resultado: al despachar se vuelve a la lista con los nuevos estados y cantidades; el botón "Refrescar" siempre recarga desde el servidor.
🎛️ Selects (combobox) con estilo activo
- Causa: el
SelectTriggerbase de shadcn (src/registry/new-york/ui/select.tsx) usababg-muted(fondo gris) +border-input(gris claro) + iconoopacity-50→ los selects de los formularios (nueva solicitud, nuevo producto) parecían inactivos/deshabilitados. - Fix (componente base, aplica a todos los selects):
bg-muted→bg-background(fondo blanco),hover:border-gray-400 hover:bg-gray-50(estado hover visible), iconoopacity-70. - Borde de color en formularios: los
SelectTrigger/combobox derequest-form.tsxyproduct-form.tsxpasaron deborder-2 border-gray-500aborder-2 !border-blue-400 hover:!border-blue-600(azul visible sobre el fondo azul suave del formulario). Se eliminó unstyle={{ border: '1px solid gray' }}que forzaba gris en el campo "Área origen". - Causa de "solo se ve en focus": la clase base
border-input(color custom de shadcn) se genera DESPUÉS de las utilidades de paleta (border-blue-400) en el CSS de Tailwind → el borde gris claro ganaba al azul en reposo; solo se veía el anillo de focus. Fix: en el base el borde pasó deborder-inputaborder-gray-400(visible en toda la app) y en los formularios el azul usa!importantpara ganar siempre.
↔️ "Propósito" y "Descripción" en la misma fila
- En
request-form.tsx, los campos "Propósito de la solicitud" (Select) y "Descripción" (Textarea) ocupaban cada uno una fila completa. Ahora están en un gridgrid-cols-1 md:grid-cols-2 gap-4→ comparten fila en escritorio, mejorando el balance visual de la card "Información de la Solicitud".
🏷️ Título y navegación del formulario de solicitud
- En
request-form.tsx: la card "Información de la Solicitud" ahora se titula "Creando nueva solicitud" (o "Editando Solicitud" en modo edición); se eliminó el<h2>duplicado que estaba frente al botón; el botón pasó de "Volver" a "Volver a la lista" (mismo estilo/tamaño que productos) y quedó alineado con la card. - En
products.tsx: se quitó elmx-2del contenedor del título "Catálogo de productos" → título, botón "Volver a la lista" y card del formulario comparten la misma margen izquierda. - En
product-form.tsx: título de la card del formulario de producto con el mismo wording del patrón → "Creando nuevo producto" (crear) / "Editando producto" (editar). - Márgenes laterales iguales: el contenedor de
products.tsxahora usapx-2(igual quesolicitudes/page.tsx) → el formulario de producto tiene el mismo margen lateral que el de solicitud.
📊 Inventario: "Cargar Stock" oculta el panel de estadísticas
- En
inventory-dashboard.tsx, al hacer clic en "Cargar Stock" ahora también se ejecutasetShowStats(false)→ el panel de tarjetas de estadísticas se oculta automáticamente para dar protagonismo a la carga de inventario (además de abrir elStockLoading). El panel puede volver a mostrarse con el botón de ojo (toggle).
📐 Inventario: reorden de cards (carga de stock arriba de Filtros)
- En
inventory-dashboard.tsxel orden de bloques cambió: antes era Estadísticas → Filtros → StockLoading → Cards principales. Ahora: Estadísticas → StockLoading (formulario de carga) → Filtros → Cards principales ("Resumen de Inventario", "Movimientos de Inventario" y "Detalle de Inventario"). La card de Filtros queda siempre encima de las cards principales y debajo del formulario de carga de stock.
📏 Select de Producto más ancho en filtros de "Gestión de Inventario"
- Página correcta: el título "Gestión de Inventario" está en
inventory-dashboard.tsx(no eninventory-movements.tsx). El filtro Producto de su barra de filtros teníamd:w-48(192px fijos) → nombres cortados. Ahora usamd:flex-1 md:min-w-48conSelectTrigger w-full min-w-0: crece para llenar el espacio restante del contenedor flex (como los selects de los formularios). - (Adicional) En
inventory-movements.tsx(Movimientos de Inventario), el filtro Producto también se amplió: ahora ocupa una fila completa (w-full) debajo del grid de filtros, con la fila superior rebalanceada (Buscar 3 + Tipo 2 + Fechas 1+1).
🔔 Notificaciones de solicitudes: registro en BD al aprobar / cancelar / despachar
- Validación: el socket SÍ se emitía (eventos
request-status-updatedcon actionapproved/rejected/status-updatedal aprobar, rechazar, cancelar y despachar — broadcast, el solicitante conectado lo recibe). PERO no se registraba ninguna notificación en la tablanotifications:SolicitudesServiceno inyectabaNotificationService, por lo que el Centro de Notificaciones (que lee de BD) quedaba vacío para estos eventos. - Fix backend (
ccf-almacen-api):SolicitudesModuleimportaNotificationModule;SolicitudesServiceinyectaNotificationServicey registra notificación dirigida al solicitante (userId = idSolicitante) en:aprobarSolicitud→ eventosolicitud_aprobada, prioridad 1rechazarSolicitud→ eventosolicitud_rechazada, con motivo, prioridad 1updateEstado→solicitud_cancelada,solicitud_despachada(completada) ysolicitud_en_proceso(inicio de despacho), prioridad 3- Método
registrarNotificacionSolicitudfire-and-forget (no rompe la respuesta HTTP); canalapp, tiposolicitud, módulosolicitudes.
- Fix frontend (
ccf-almacen-web):getUnreadCountusaba el usuario 1 hardcodeado (/unread/count/1); ahora recibe eluserIddel usuario logueado desdenotification-tray.tsx.
Filtrado por usuario en el Centro de Notificaciones (Admin ve todas)
- Backend:
NotificationService.findAllNotification(userId?)filtra porid_creado_por(destinatario) si llega el parámetro.NotificationController.findAllobtiene el usuario autenticado (req.user) y aplica la regla: Admin ve todas o filtra con?userId=; no-admin siempre ve solo sus propias notificaciones (forzado por backend). - Frontend:
getRecentNotifications(limit, userId?)envía el filtro;Notificationsacepta propuserId;notification-tray.tsxpasa elidUsuariodel usuario logueado y, si es Admin, muestra un selector "Filtrar por usuario" (Todos los usuarios + lista) que controla el listado.
🔄 Panel lateral: solicitudes abiertas y recientes se refrescan por socket
open-requests.tsx: ya escuchabarequest-status-updated, pero solo actualizaba la lista local (top-10) sin consultar el servidor. Ahora, al recibir el evento, además de actualizar localmente hace un refetch completo (refreshOpenRequests, sin tocar el estado de loading para no parpadear) → las solicitudes despachadas/completadas/canceladas salen del panel.recent-requests.tsx: (bug) NO escuchabarequest-status-updatedy ni siquiera hacía fetch inicial (solo se llenaba con eventos en vivo). Ahora: carga inicial desde la API (getAllRequests/getRequestsBySolicitante), escucharequest-status-updated(filtra las abiertas: pendiente/aprobada/en_proceso + refetch) y mantienenew-request-created.- Resultado: al terminar un despacho (o cualquier cambio de estado), el panel lateral derecho se actualiza en todos los clientes conectados sin recargar la página, igual que la lista principal.
🔥 Borde de gradiente animado en cards de prioridad "Urgente"
- Nuevo
src/styles/urgent-border.css: clase.urgent-border-cardque dibuja un gradiente cónico (rojo→naranja→ámbar) recorriendo el borde en secuencia (animación de ángulo con@property --urgent-angle+ keyframes). Se usa máscaracontent-box xorpara que el gradiente se vea solo en el borde (2px), sin sombras ni difuminaciones. Fallback: navegadores sin conic-gradient muestran borde rojo fijo;prefers-reduced-motionlo deja estático. - Aplicado en cards/solicitudes con prioridad Urgente:
open-request-item.tsx(panel lateral "Solicitudes Abiertas" — expandida y colapsada)recent-request-item.tsx(panel lateral "Solicitudes Recientes")mobile-requests.tsx(cards de la vista móvil de solicitudes)
🎨 Botones de la página de inicio: de rojo a azul primario
- En
general-dashboard.tsx, los botones "Ver todas las alertas" (panel Alertas de Stock) y "Ver todos los movimientos" (panel Movimientos Recientes) usabanthemes[currentTheme].buttonDanger(rojo). Al ser botones de navegación/ver más (no destructivos), ahora usanbuttonPrimary(gradiente índigo→azul), consistente con los demás botones de navegación. - El filtro "Salida" del gráfico mensual conserva el rojo (
buttonDanger) porque ahí es semántico (movimiento de salida). - Ajuste: en el tema de grises,
buttonPrimaryera negro (bg-gray-900). Los dos botones ahora usan azul fijobg-gradient-to-r from-blue-600 to-blue-800 hover:from-blue-700 hover:to-blue-900 text-white hover:text-white border-0(patrón "Volver a la lista") → siempre azules con texto blanco (también en hover).
🔔 Notificación de "usuario conectado" (toast a usuarios en sesión)
- Backend (
appGateway.gateway.ts): en el handleridentifyUser, además de registrar al usuario y emitirusers-update, ahora busca el usuario completo en BD y emite el eventouser-connecteda todos los clientes con{ idUsuario, nombreCompleto, usuario, rol, avatar, idOficina, timestamp }(fire-and-forget). - Frontend (
sidebar.tsx): al conectar el socket (y reconectar), emiteidentifyUsercon el id/username del usuario logueado (antes no se emitía); escuchauser-connectedy muestra un toast Sonner ("Usuario conectado: {nombre}", descripción "Rol: {rol}") — el propio usuario no recibe su propia notificación. - Resultado: cuando alguien inicia sesión y aparece en el panel lateral de usuarios en línea, los demás usuarios en sesión ven la notificación con sus datos.
- Fix duplicados: la notificación salía varias veces porque el efecto del sidebar se re-ejecutaba durante la hidratación y cada ejecución volvía a emitir
identifyUser→ el backend emitía Nuser-connected. Ahora se usa unref(identifiedUserIdRef) que garantiza emitiridentifyUseruna sola vez por usuario. - Fix 0 notificaciones: el efecto pasó a correr UNA sola vez al montar (
deps []) con uncurrentUserRefactualizado en cada render → el listener deuser-connectedqueda estable y no se pierde por re-ejecuciones del efecto (carrera con el evento). El ref se resetea al desconectar para permitir re-identificar en reconexiones reales (no en re-renders ni StrictMode).
📥 Bandeja de entrada de solicitudes (opción 2 implementada)
- Nuevo componente
src/components/requests/request-inbox.tsx: vista kanban de solicitudes con:- Tarjetas de métricas (5): solicitudes este año, despachadas, pendientes, novedades de entrega (rechazadas/canceladas) y urgentes.
- Buscador por código, propósito, solicitante o área + botón "Escala de grises" (alterna
grayscaledel panel, como documenta el manual). - Columnas por estado: "Recién Solicitadas" (pendiente), "En Gestión" (aprobada/en proceso), "Entregadas" (completada).
- Detalle en columna derecha: al seleccionar una solicitud se muestra
RequestDetailStandalone(estado, prioridad, fechas, solicitante, productos, acciones por rol). El grid pasó delg:grid-cols-4alg:grid-cols-5con el detalle enlg:col-span-2→ la card "Detalle de Solicitud" ocupa 2/5 del ancho y el contenido ya no se desborda.
- Patrón visual de inventario aplicado:
request-inbox.tsxahora usa el mismo sistema de temas que las cards de inventario (Resumen de Inventario,Movimientos de Inventario,Detalle del Movimiento): temascolorful/grayscale(persistido enlocalStorage 'dashboard-theme'), cards conthemes.card(gradiente slate oscuro o blanco), headers con icono +textColor, badgesbadge.secondary/normal/low/out,inputBg,selectedBgy separadores. Botón de tema (Palette) en el header.- Filtra por solicitante si el usuario es "Usuario Interno".
- Menú: ítem "Bandeja de entrada" (
_id 10, iconoInboxIcon) arriba de "Solicitudes" ensidebar-option.ts, visible para Admin/Almacenista y Usuario Interno. El manualbandeja-entrada.mddescribe esta vista y quedó alineado.
🔕 Toast de "usuario conectado" retirado
- La notificación toast al conectar un usuario se intentó implementar (backend
user-connected+ listener ensidebar.tsx), pero producía toasts duplicados (hasta 3 veces) difíciles de estabilizar (reconexiones del socket, re-renders/StrictMode, hidratación). - Decisión: se retiró por completo — se eliminó el
emit user-connecteddel backend (appGateway.gateway.ts) y el listener/toast del frontend (sidebar.tsx). Se mantiene solo la identificación del socket (identifyUser, con ref guard emitido 1 sola vez por usuario) que alimenta el panel de usuarios en línea (users-update).
Resumen consolidado de la fase: ver
RESUMEN-FASE-MODULO-ALMACEN.mden la raíz del monorepo (informe con archivos, verificaciones y guía de validación).
📚 Regla de documentación obligatoria- Nuevo ccf-almacen-framework/DOCUMENTATION.md: todo cambio se documenta en esta wiki (manual y/o changelog) al implementarse.
- La regla se integró en
AGENT.md(prohibición 17),DECISION_TREE.md(regla 11),REVIEW_PROTOCOL.md(Fase 8) yPHILOSOPHY.md(Mandamiento IV). - Guía para desarrolladores: Documentación de Cambios.
