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

# MCH-022: Modo Offline

## Metadata
- **Codigo:** MCH-022
- **Fase:** 6 - Crecimiento
- **Prioridad:** P1
- **Estado:** Pendiente
- **Fecha estimada:** Sprint 13-14

## 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
```typescript
// 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-07