Sincronización
El sistema POS utiliza una arquitectura de sincronización híbrida que combina conexiones WebSocket para actualizaciones en tiempo real y HTTP para transferencias masivas de datos. Este diseño asegura que las tiendas operen independientemente mientras se mantienen consistentes con HQ.
Cómo Funciona la Sincronización
Cada servidor de tienda mantiene una conexión WebSocket persistente al servidor de sincronización de HQ (en el puerto definido por SYNC_LISTEN_PORT). Cuando los datos cambian en HQ -- como un nuevo producto, precio actualizado o cambio de rol -- el servidor de sincronización envía una notificación a todas las tiendas conectadas a través del WebSocket. La tienda entonces obtiene los registros modificados mediante una llamada a la API HTTP.
En la dirección opuesta, las tiendas envían datos locales (transacciones de venta, Reportes Z, ajustes de inventario, actualizaciones de transferencias) a HQ en un intervalo regular (por defecto: cada 60 segundos) o inmediatamente para ciertos eventos de alta prioridad. Este envío ocurre mediante solicitudes HTTP POST a la API de sincronización de HQ.
Qué Se Sincroniza y en Qué Dirección
De HQ a Tiendas (descendente):
- Productos (crear, actualizar, desactivar)
- Departamentos (crear, actualizar, desactivar)
- Tasas de impuesto (crear, actualizar)
- Usuarios y asignaciones de roles
- Registros de transferencias de otras tiendas
De Tiendas a HQ (ascendente):
- Transacciones de venta completadas
- Reportes Z y Reportes ZZ
- Ajustes de inventario
- Actualizaciones de estado de transferencias (despachado, recibido)
- Datos de sesiones de caja
Los datos de productos y configuración fluyen solo de HQ a las tiendas. Las tiendas no pueden modificar productos ni tasas de impuesto localmente. Los datos de transacciones fluyen solo de las tiendas a HQ. Este enfoque unidireccional por tipo de dato previene conflictos.
Comportamiento Sin Conexión
Cuando una tienda pierde conectividad con HQ, continúa operando normalmente. Todas las funciones del Terminal POS y Gerente de Tienda funcionan sin interrupción porque dependen de la base de datos PostgreSQL local. Los cambios de datos se acumulan localmente y se ponen en cola para sincronización.
Cuando se restaura la conectividad, el servidor de la tienda detecta la reconexión y comienza a sincronizar los datos en cola. Los cambios descendentes de HQ (por ejemplo, nuevos productos agregados mientras la tienda estaba sin conexión) también se obtienen durante este período de recuperación. El motor de sincronización procesa los cambios en orden cronológico para mantener la consistencia.
No hay límite de tiempo para la operación sin conexión. Una tienda puede funcionar por días o semanas sin sincronizar, y todos los datos acumulados eventualmente se sincronizarán cuando regrese la conectividad. Sin embargo, los períodos extendidos sin conexión significan que la tienda no recibirá actualizaciones de productos, cambios de precios o nuevas asignaciones de usuarios hasta que se reconecte.
Solución de Problemas de Sincronización
Verifique el indicador de estado de sincronización en el panel del Gerente de Tienda. Un indicador verde significa que la conexión WebSocket está activa. Rojo significa desconectado. Los problemas comunes incluyen:
- Reglas de firewall: Asegúrese de que el puerto de sincronización de HQ (por defecto 3001) esté abierto para tráfico WebSocket.
- Expiración de certificado TLS: Si usa HTTPS/WSS, verifique que los certificados estén vigentes.
- Resolución DNS: La tienda debe poder resolver el nombre de host de HQ.
- Revocación de token: Si el token de sincronización fue revocado en el Gerente HQ, genere uno nuevo y actualice la configuración de la tienda.
Revise los logs del servidor de la tienda en logs/store-server.log para mensajes detallados de errores de sincronización.