Saltar al contenido principal

Release — Mejoras de UX, sockets y documentación (Agosto 2026)

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

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 campo codigo en CreateProductoDto ahora 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: handleConnection con try/catch (ya no aborta el handshake si falla la BD); nuevo método liviano UsuariosService.findLogeado(); nuevo evento request-status-updated emitido en aprobar/rechazar/cambiar estado/actualizar solicitudes; logout ahora emite users-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.mjs en next.config.js (se eliminó el duplicado; se preservaron los images.remotePatterns necesarios para avatars.githubusercontent.com).
  • Actualizado CLIENT_SOCKET en el .env del API al host real de producción.

🏷️ Patrón visual: badges robustos​

  • Componente base badge.tsx con 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. Package para producto, Lock para 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 el Toaster de src/registry/new-york/ui/toaster.tsx. Ese componente salía sin iconos y en blanco/negro (bg-background text-foreground) y sin data-type, por lo que los estilos de toast-improvements.css (.toast[data-type=...]) nunca aplicaban. Solo una minoría usa Sonner directo.
  • Solución (toaster shadcn): ui/toaster.tsx ahora resuelve el tono semántico del toast (data-type si 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).
  • Solución (Sonner): se eliminó el fondo blanco forzado del SonnerToaster en sidebar.tsx (toastOptions.style) y se sobrescribieron las variables CSS de Sonner en src/styles/toast-improvements.css con 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 solo w-20 con el borde tenue por defecto de shadcn → se perdía entre la fila.
  • Ahora el input tiene: w-24, texto centrado y seminegrita, borde border-2 gris visible (border-gray-400), fondo bg-gray-50 con sombra, hover:border-gray-500 y foco verde institucional (focus:border-green-500 focus:ring-green-500/30). Los estados de completado (verde bg-green-50) y error (rojo bg-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-tooltip id my-tooltip-t, ya montado en auth-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 un AlertDialog (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 (reutiliza ACTION_TOOLTIPS como descripción) antes de cambiar el estado.
  • Patrón: AlertDialog de src/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 respeta prefers-reduced-motion. Variantes sm/md/lg y label opcional.
  • LoadingState (data-states.tsx) ahora usa el componente (beneficia a product-list y futuros usos).
  • Reemplazados todos los spinners HTML estáticos (animate-spin rounded-full border-b-2) de páginas por LoadingIndicator: 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 → ahora w-full min-w-0 (ocupa su columna del grid de 4).
    • "Tipo de Solicitud": max-w-[120px] ml-12 (diminuto) → ahora w-full min-w-0 (sin margen artificial).
    • "Prioridad": max-w-[120px] (diminuto) → ahora w-full min-w-0.
  • Resultado: los Select ocupan el ancho de su columna dentro del grid md: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, porque solicitudes/page.tsx pasa un initialData con valores por defecto (sin idSolicitud) también en modo CREATE (el condicional initialData ? "Editar" : "Nueva" era truthy).
  • Ahora usa el mismo criterio que onSubmitForm para 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.tsx perdió el max-w-4xl mx-auto → ahora el formulario de producto usa w-full como 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ía FormDescription en 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: onDispatchComplete solo hacía setViewState(LIST) (sin fetchRequests()), a diferencia de los flujos de eliminar/guardar/cambiar estado. El botón "Refrescar" tampoco recargaba porque handleRefresh solo reseteaba estados que, sin búsqueda activa, no cambiaban (React no re-renderizaba y no había refetch).
  • Fix en solicitudes/page.tsx: onDispatchComplete ahora hace setViewState(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 pasa onRefresh={fetchRequests} a RequestList.
  • Fix en request-list.tsx: nueva prop opcional onRefresh; 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 SelectTrigger base de shadcn (src/registry/new-york/ui/select.tsx) usaba bg-muted (fondo gris) + border-input (gris claro) + icono opacity-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), icono opacity-70.
  • Borde de color en formularios: los SelectTrigger/combobox de request-form.tsx y product-form.tsx pasaron de border-2 border-gray-500 a border-2 !border-blue-400 hover:!border-blue-600 (azul visible sobre el fondo azul suave del formulario). Se eliminó un style={{ 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ó de border-input a border-gray-400 (visible en toda la app) y en los formularios el azul usa !important para 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 grid grid-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ó el mx-2 del 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.tsx ahora usa px-2 (igual que solicitudes/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 ejecuta setShowStats(false) → el panel de tarjetas de estadísticas se oculta automáticamente para dar protagonismo a la carga de inventario (además de abrir el StockLoading). 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.tsx el 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 en inventory-movements.tsx). El filtro Producto de su barra de filtros tenía md:w-48 (192px fijos) → nombres cortados. Ahora usa md:flex-1 md:min-w-48 con SelectTrigger 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-updated con action approved/rejected/status-updated al aprobar, rechazar, cancelar y despachar — broadcast, el solicitante conectado lo recibe). PERO no se registraba ninguna notificación en la tabla notifications: SolicitudesService no inyectaba NotificationService, por lo que el Centro de Notificaciones (que lee de BD) quedaba vacío para estos eventos.
  • Fix backend (ccf-almacen-api): SolicitudesModule importa NotificationModule; SolicitudesService inyecta NotificationService y registra notificación dirigida al solicitante (userId = idSolicitante) en:
    • aprobarSolicitud → evento solicitud_aprobada, prioridad 1
    • rechazarSolicitud → evento solicitud_rechazada, con motivo, prioridad 1
    • updateEstado → solicitud_cancelada, solicitud_despachada (completada) y solicitud_en_proceso (inicio de despacho), prioridad 3
    • Método registrarNotificacionSolicitud fire-and-forget (no rompe la respuesta HTTP); canal app, tipo solicitud, módulo solicitudes.
  • Fix frontend (ccf-almacen-web): getUnreadCount usaba el usuario 1 hardcodeado (/unread/count/1); ahora recibe el userId del usuario logueado desde notification-tray.tsx.

Filtrado por usuario en el Centro de Notificaciones (Admin ve todas)​

  • Backend: NotificationService.findAllNotification(userId?) filtra por id_creado_por (destinatario) si llega el parámetro. NotificationController.findAll obtiene 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; Notifications acepta prop userId; notification-tray.tsx pasa el idUsuario del 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 escuchaba request-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 escuchaba request-status-updated y ni siquiera hacía fetch inicial (solo se llenaba con eventos en vivo). Ahora: carga inicial desde la API (getAllRequests/getRequestsBySolicitante), escucha request-status-updated (filtra las abiertas: pendiente/aprobada/en_proceso + refetch) y mantiene new-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-card que 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áscara content-box xor para 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-motion lo 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) usaban themes[currentTheme].buttonDanger (rojo). Al ser botones de navegación/ver más (no destructivos), ahora usan buttonPrimary (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, buttonPrimary era negro (bg-gray-900). Los dos botones ahora usan azul fijo bg-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 handler identifyUser, además de registrar al usuario y emitir users-update, ahora busca el usuario completo en BD y emite el evento user-connected a todos los clientes con { idUsuario, nombreCompleto, usuario, rol, avatar, idOficina, timestamp } (fire-and-forget).
  • Frontend (sidebar.tsx): al conectar el socket (y reconectar), emite identifyUser con el id/username del usuario logueado (antes no se emitía); escucha user-connected y 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 N user-connected. Ahora se usa un ref (identifiedUserIdRef) que garantiza emitir identifyUser una sola vez por usuario.
  • Fix 0 notificaciones: el efecto pasó a correr UNA sola vez al montar (deps []) con un currentUserRef actualizado en cada render → el listener de user-connected queda 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 grayscale del 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ó de lg:grid-cols-4 a lg:grid-cols-5 con el detalle en lg: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.tsx ahora usa el mismo sistema de temas que las cards de inventario (Resumen de Inventario, Movimientos de Inventario, Detalle del Movimiento): temas colorful/grayscale (persistido en localStorage 'dashboard-theme'), cards con themes.card (gradiente slate oscuro o blanco), headers con icono + textColor, badges badge.secondary/normal/low/out, inputBg, selectedBg y 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, icono InboxIcon) arriba de "Solicitudes" en sidebar-option.ts, visible para Admin/Almacenista y Usuario Interno. El manual bandeja-entrada.md describe 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 en sidebar.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-connected del 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.md en 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) y PHILOSOPHY.md (Mandamiento IV).
  • Guía para desarrolladores: Documentación de Cambios.