Playbook: Sincronización y Modo Offline

Problema 1: La app no sincroniza al recuperar internet

Síntomas

El indicador de conexión vuelve a verde, pero las órdenes no suben.
Las facturas electrónicas siguen como “Pendiente local”.
Los datos del portal web no reflejan las ventas recientes.

Diagnóstico

Verificar indicador de conexión — Debe estar en verde (no naranja ni rojo).
- Verde: Conectado y sincronizando.
- Naranja: Conexión intermitente — sincronización parcial.
- Rojo: Sin conexión.
Verificar la cola de sync — En la app, ve al menú lateral > Estado de Sincronización.
Verificar que la sesión no haya expirado — Si llevas mucho tiempo offline, el token JWT puede haber expirado.

Solución

Causa	Acción
Conexión intermitente (naranja)	Acércate al router o cambia a una red más estable. La sync se reanuda automáticamente.
Sesión expirada	Cierra sesión y vuelve a iniciar. Las órdenes locales se conservan y se sincronizarán al reloguearte.
Cola bloqueada	Cierra la app completamente (no solo minimizar) y vuelve a abrirla. La sync se reinicia automáticamente.
Error de servidor	Si persiste después de reiniciar la app, contacta soporte — puede haber un problema con el backend.

Prevención

Mantener WiFi estable en el punto de venta.
No dejar la app en background por más de 24 horas sin conexión.
Sincronizar manualmente antes de cerrar turno (ver Estado de Sincronización).

Problema 2: Consecutivos desincronizados

Síntomas

El número de factura salta (ej: de 100 a 150).
Dos dispositivos generan el mismo número de factura.
Error al enviar a DGI: “Consecutivo ya utilizado”.

Diagnóstico

Verificar consecutivo actual — En la app: Ajustes > Terminal. Muestra el consecutivo local actual.
Comparar con el servidor — En el portal web: Configuración > Terminales > ver el consecutivo del terminal.
Identificar si hubo uso offline prolongado — Si dos tablets operaron offline al mismo tiempo con el mismo terminal, pueden haber generado consecutivos duplicados.

Cómo funciona el sistema de consecutivos

Online:  La app pide el siguiente número al servidor (con lock).
Offline: La app usa un consecutivo local incrementado.
Sync:    Al reconectar, si el local > servidor, el servidor se actualiza.
         Si el local < servidor, la app se actualiza al valor del servidor.

Solución

Escenario	Acción
Salto en numeración	Es normal si hubo operación offline. Los consecutivos locales se sincronizaron. No requiere acción.
Duplicado entre dispositivos	Contacta soporte. Se necesita reasignar consecutivos manualmente para uno de los terminales.
Error DGI por consecutivo	No reintentar — el consecutivo ya fue usado. La siguiente factura usará un consecutivo válido automáticamente.

Prevención

Un terminal = un dispositivo. No usar el mismo terminal en dos tablets simultáneamente.
Si necesitas dos tablets, registra dos terminales diferentes.
Sincronizar antes de apagar la tablet al final del día.

Problema 3: Conflictos de datos multi-dispositivo

Síntomas

Un producto editado en el portal no se refleja en la app.
El precio de un producto difiere entre la app y el portal.
Un cliente creado en la app no aparece en el portal (o viceversa).

Diagnóstico

Verificar última sincronización — En la app, ve al menú lateral > Estado de Sincronización. Revisa la fecha/hora del último sync exitoso.
Verificar conexión — El indicador debe estar en verde.
Forzar sync manual — Tira hacia abajo (pull-to-refresh) en la pantalla principal.

Solución

Causa	Acción
Sync no se ha ejecutado	Fuerza un sync manual desde la app (pull-to-refresh o botón de sync).
Dato editado offline en ambos lados	El dato más reciente gana. Si se editó el mismo campo en la app y en el portal sin conexión, el último en sincronizar prevalece.
Producto nuevo no aparece	Fuerza sync en la app. Si no aparece después de sync, verifica que el producto esté asignado a la sucursal correcta.

Prevención

Hacer cambios de catálogo (precios, productos) desde el portal web con la app conectada.
Evitar editar el mismo registro simultáneamente desde la app y el portal.
Revisar el estado de sync antes de cambios importantes.

Problema 4: Órdenes offline no aparecen en reportes

Síntomas

Hiciste ventas offline pero no aparecen en los reportes del portal.
El total de ventas del día no cuadra.

Diagnóstico

Verificar sync completado — Las órdenes offline deben haberse sincronizado (indicador verde, sin pendientes en cola).
Verificar filtro de fecha — Las órdenes offline se registran con la fecha/hora de creación local, no la de sincronización.
Verificar terminal — Los reportes pueden filtrar por terminal; asegúrate de incluir el terminal correcto.

Solución

Abre la app y verifica que todas las órdenes se sincronizaron (Estado de Sincronización > 0 pendientes).
En el portal, refresca el reporte.
Si las órdenes son de ayer y estás viendo el reporte de hoy, cambia el filtro de fecha.

Guión del Video

Título: “Modo Offline y Sincronización en NAOS — Cómo funciona y cómo resolver problemas”

Duración estimada: 6-8 minutos

Tiempo	Escena	Acción	Narración
0:00	Intro	Logo NAOS + título	”NAOS funciona sin internet. En este video te explicamos cómo funciona el modo offline y qué hacer si algo no sincroniza.”
0:20	App - Indicadores	Mostrar los 3 estados (verde/naranja/rojo)	“Este indicador te dice el estado de tu conexión. Verde es todo bien, naranja es intermitente, y rojo es sin conexión.”
0:50	App - Venta offline	Hacer una venta con indicador rojo	”Puedes vender normalmente sin internet. La app guarda todo localmente.”
1:30	App - Reconexión	Cambiar a verde, mostrar sync automático	”Al recuperar internet, las órdenes se sincronizan automáticamente. Mira cómo el indicador cambia a verde.”
2:00	App - Estado de Sync	Menú lateral > Estado de Sincronización	”Aquí puedes ver cuántas órdenes y facturas están pendientes de sincronizar.”
2:40	Diagrama	Animación de consecutivos	”Los consecutivos funcionan así: online, la app pide el siguiente número al servidor. Offline, usa un contador local. Al reconectar, se sincronizan.”
3:30	App - Problema sesión	Mostrar sesión expirada	”Si estuviste mucho tiempo offline, puede que tu sesión expire. Solo cierra sesión y vuelve a entrar — tus ventas se conservan.”
4:00	App - Forzar sync	Pull-to-refresh	”Si algo no sincroniza, tira hacia abajo para forzar la sincronización manualmente.”
4:30	Portal - Reportes	Mostrar reporte sin ventas offline	”Las ventas offline aparecen en los reportes cuando se sincronizan. Si no las ves, verifica que la app ya sincronizó y que el filtro de fecha es correcto.”
5:00	Regla de oro	Pantalla con texto	”Regla de oro: un terminal, un dispositivo. Nunca uses el mismo terminal en dos tablets al mismo tiempo.”
5:30	App - Dos tablets	Mostrar configuración de dos terminales	”Si necesitas dos tablets, registra dos terminales diferentes. Así cada uno tiene sus propios consecutivos.”
6:00	Tips	Checklist en pantalla	”Antes de cerrar turno: verifica que todo sincronizó. Mantén WiFi estable. Y nunca edites consecutivos manualmente.”
6:30	Cierre	Logo + soporte	”¿Tienes un problema de sync que no puedes resolver? Contacta a soporte en naos.pa/soporte.”