michangarrito/docs/01-epicas/MCH-022-modo-offline.md

id	type	title	code	status	phase	priority	created_at	updated_at	simco_version	dependencies
EPIC-MCH-022	Epic	MCH-022: Modo Offline	MCH-022	Completado	6	P1	2026-01-10	2026-01-10	3.8.0	blocks depends_on

MCH-022: Modo Offline

Metadata

• Codigo: MCH-022
• Fase: 6 - Crecimiento
• Prioridad: P1
• Estado: Completado
• Fecha completado: 2026-01-10

Descripcion

Soporte offline completo para la app movil: SQLite local, sincronizacion inteligente, resolucion de conflictos, y funcionamiento sin conexion para operaciones criticas (ventas).

Objetivos

1. Base de datos local (SQLite)
2. Sincronizacion bidireccional
3. Ventas sin conexion
4. Resolucion de conflictos
5. Indicador de estado de conexion

Alcance

Incluido

• SQLite para datos locales
• Sync de productos, clientes, ventas
• Cola de operaciones offline
• Resolucion automatica de conflictos
• Indicador visual de estado

Excluido

• Offline para dashboard web
• Sync de imagenes pesadas
• Operaciones de pago offline (solo efectivo)

Arquitectura

┌─────────────────────────────────────────────────────────┐
│                      APP MOVIL                          │
├─────────────────────────────────────────────────────────┤
│                                                         │
│  ┌─────────────┐    ┌─────────────┐    ┌────────────┐  │
│  │   UI Layer  │───▶│  Repository │───▶│   SQLite   │  │
│  └─────────────┘    └──────┬──────┘    └────────────┘  │
│                            │                            │
│                     ┌──────▼──────┐                     │
│                     │  Sync Queue │                     │
│                     └──────┬──────┘                     │
│                            │                            │
└────────────────────────────┼────────────────────────────┘
                             │
                      ┌──────▼──────┐
                      │   Backend   │
                      │     API     │
                      └─────────────┘

Datos Sincronizados

Alta Prioridad (Sync inmediato)

Tabla	Direccion	Frecuencia
products	Server → Local	Al iniciar + cada 5 min
categories	Server → Local	Al iniciar
sales	Local → Server	Inmediato cuando hay conexion

Media Prioridad

Tabla	Direccion	Frecuencia
customers	Bidireccional	Cada 15 min
inventory	Server → Local	Cada 30 min

Baja Prioridad

Tabla	Direccion	Frecuencia
settings	Server → Local	Al iniciar
reports	No sync (solo online)	-

Flujo de Venta Offline

1. App detecta sin conexion
2. Usuario hace venta normal
3. Venta se guarda en SQLite
4. Se agrega a cola de sync
5. UI muestra "Venta guardada offline"
6. Cuando hay conexion:
   a. Cola procesa ventas pendientes
   b. Envia al servidor
   c. Actualiza IDs locales
   d. Marca como sincronizado

Resolucion de Conflictos

Estrategia: Last Write Wins + Merge

// Para productos
if (local.updated_at > server.updated_at) {
  // Local gana
  sync.upload(local);
} else if (server.updated_at > local.updated_at) {
  // Server gana
  sync.download(server);
} else {
  // Merge campos no conflictivos
  sync.merge(local, server);
}

Casos Especiales

Venta offline con producto eliminado:

1. Producto vendido offline
2. Producto eliminado en server
3. Al sync: venta se registra con producto_id
4. Se marca producto como "deleted" localmente

Stock desactualizado:

1. Venta offline reduce stock local
2. Otra venta online reduce stock
3. Al sync: stock negativo posible
4. Alerta al dueno para ajuste

Modelo de Datos Local (SQLite)

Tablas Adicionales

sync_queue

• id, operation (create/update/delete)
• table_name, record_id, payload
• status, attempts, created_at

sync_status

• table_name, last_sync_at
• records_count, pending_count

UI Components

ConnectionIndicator

• Icono en header
• Verde: online
• Amarillo: sync pendiente
• Rojo: offline

OfflineBanner

• Banner visible cuando offline
• "Modo offline - cambios se sincronizaran"

SyncProgress

• Modal de sincronizacion
• Progreso por tabla
• Errores si hay

Tecnologias

• SQLite: react-native-sqlite-storage o expo-sqlite
• Sync: Custom sync engine o WatermelonDB
• Network: NetInfo para detectar conexion

Entregables

Entregable	Estado	Archivo
SQLite setup	Pendiente	mobile/database/
Sync engine	Pendiente	mobile/sync/
Offline queue	Pendiente	mobile/sync/queue.ts
ConnectionIndicator	Pendiente	mobile/components/

Dependencias

Depende de

• MCH-004 (Sales module)
• MCH-003 (Products module)
• App movil base

Bloquea a

• Ninguno (mejora de UX)

Criterios de Aceptacion

• App funciona sin conexion
• Ventas se guardan offline
• Sync funciona al reconectar
• Conflictos se resuelven
• Indicador de estado visible

Limitaciones Offline

Funcion	Disponible Offline
Ver productos	Si
Hacer venta (efectivo)	Si
Hacer venta (tarjeta)	No
Ver clientes	Si
Chat IA	No
Reportes	No
Configuracion	Solo lectura

---

Ultima actualizacion: 2026-01-10