betuko_offline_sync

🐛 Corrección de Bug Crítico

Prevención de Doble POST al Reconectar

Se corrigió un problema donde al volver de offline a online, a veces se ejecutaban múltiples sincronizaciones simultáneas causando doble POST de los mismos datos.

Cambios implementados:

1. Protección en syncAll(): Se agregó un flag _isSyncingAll para prevenir múltiples ejecuciones simultáneas de syncAll(). Ahora si se llama desde diferentes lugares al mismo tiempo (reconexión automática, WorkManager, llamada manual), solo se ejecuta una vez.

2. Protección en _handleReconnection(): Ya existía un flag _isHandlingReconnection, pero ahora está mejor documentado y garantiza que solo una reconexión se procese a la vez.

3. WorkManager con ExistingWorkPolicy.replace: Se aseguró que syncWhenConnected() use un nombre fijo y reemplace tareas existentes en lugar de crear múltiples tareas duplicadas.

Resultado: Ahora hay protección en 3 niveles para evitar ejecuciones simultáneas y garantizar que cada dato se sincronice solo una vez.

✨ Nuevas Características

Control de Upload (POST) por Manager

Ahora puedes controlar qué managers hacen POST (subida) y cuáles solo hacen GET (descarga):

// Manager con POST habilitado (sube y descarga)
final asistencias = OnlineOfflineManager(
  boxName: 'asistencias',
  endpoint: 'processes/payroll/daily-capture',
  uploadEnabled: true, // ✅ Permite POST
);

// Manager solo lectura (solo descarga, no sube)
final catalogos = OnlineOfflineManager(
  boxName: 'catalogos',
  endpoint: 'catalogs/items',
  uploadEnabled: false, // ❌ Solo GET
);

Valor por defecto: uploadEnabled: false (solo GET por defecto)

Mejoras en Background Sync

• Inicialización automática de ConnectivityService en background
• Mejor manejo de errores: Los errores de POST ya no se silencian, se propagan correctamente
• Logs mejorados: Uso de developer.log() para que aparezcan en logcat incluso con la app cerrada
• Detección automática: Si el boxName contiene "asistencia" o "attendance", se habilita uploadEnabled: true automáticamente en background

Mejoras en Manejo de Errores

• Los errores de POST ahora se propagan correctamente en lugar de silenciarse
• Logs detallados para cada registro que se intenta enviar
• Contadores de éxitos/fallos en sincronización
• Mejor información de errores en los resultados

📚 Documentación

• Nuevo archivo WORKMANAGER_SETUP.md con guía completa de configuración
• Documentación detallada de permisos Android requeridos
• Guía de troubleshooting para problemas comunes
• Ejemplos completos de uso

🔧 Cambios Técnicos

• OnlineOfflineManager ahora acepta parámetro uploadEnabled (default: false)
• SyncService respeta uploadEnabled y omite upload si es false
• BackgroundSyncService guarda y restaura uploadEnabled en SharedPreferences
• Mejora en logs de ApiClient usando developer.log() para background

🐛 Corrección de Bug

Verificación de conexión más robusta

• Se agregaron múltiples endpoints de verificación para redes que bloquean Google/Cloudflare
• Ahora usa la API del usuario como primer endpoint de verificación
• Timeouts más largos para conexiones lentas

Endpoints de verificación (en orden):

1. API del usuario (baseUrl configurado)
2. Google connectivity check (gstatic)
3. Google generate_204
4. Apple captive portal
5. Cloudflare 1.1.1.1
6. Google DNS

🐛 Corrección de Bug

Sincronización más confiable al reconectar

Se corrigió un problema donde la sincronización al reconectar fallaba porque connectivity_plus detectaba la conexión antes de que estuviera realmente disponible.

✨ Mejoras

Verificación de conexión real

• Nuevo método ConnectivityService.hasRealConnection() que hace un ping HTTP real para verificar conectividad
• Se usa Google's generate_204 endpoint con fallback a Cloudflare

Delay configurable antes de sincronizar

• Nuevo parámetro reconnectDelaySeconds en GlobalConfig.init() (default: 3 segundos)
• Permite que la conexión se estabilice antes de intentar sincronizar

Verificación opcional de conexión real

• Nuevo parámetro verifyRealConnection en GlobalConfig.init() (default: true)
• Si la verificación falla, reintenta una vez más antes de cancelar

📖 Uso

// Configuración por defecto (recomendada)
await GlobalConfig.init(
  baseUrl: 'https://api.com',
  token: 'tu-token',
);

// Personalizar el comportamiento de reconexión
await GlobalConfig.init(
  baseUrl: 'https://api.com',
  token: 'tu-token',
  reconnectDelaySeconds: 5,     // Esperar 5 segundos (default: 3)
  verifyRealConnection: true,   // Verificar conexión real (default: true)
);

📝 Logs mejorados

Ahora se muestra información clara sobre el proceso de reconexión:

🔄 Auto-sync: conexión detectada, esperando 3s para estabilizar...
🔍 Verificando conexión real...
✅ Conexión real verificada
🔄 Auto-sync: conexión recuperada, sincronizando...

✨ Nueva Característica Principal

🌙 Background Sync con WorkManager (Android)

Ahora puedes sincronizar datos incluso cuando la app está completamente cerrada usando WorkManager.

Características:

• Sincronización Periódica: Cada 15 minutos (mínimo permitido por Android)
• Sincronización al Reconectar: Se ejecuta automáticamente cuando hay conexión disponible
• Persistencia de Configuración: La configuración se guarda en SharedPreferences para el background isolate
• Fácil Integración: Solo requiere llamar a BackgroundSyncService.initialize()

Uso Básico:

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  
  // Configurar con background sync habilitado
  await GlobalConfig.init(
    baseUrl: 'https://api.com',
    token: 'tu-token',
    enableBackgroundSync: true,
  );
  
  // Inicializar WorkManager
  await BackgroundSyncService.initialize();
  
  // Crear y registrar managers
  final reportes = OnlineOfflineManager(
    boxName: 'reportes',
    endpoint: '/api/reportes',
  );
  await BackgroundSyncService.registerManager(reportes);
  
  // Iniciar sync periódico
  await BackgroundSyncService.startPeriodicSync();
  
  runApp(MyApp());
}

🆕 Nuevas Clases y Métodos

BackgroundSyncService

GlobalConfig Actualizado

• init() ahora es async y acepta enableBackgroundSync
• Nuevo método initSync() para inicialización síncrona
• Nuevo método saveForBackgroundSync()
• Nuevo método loadFromPrefs()
• updateToken() ahora es async y actualiza SharedPreferences

📦 Nuevas Dependencias

• workmanager: ^0.9.0+3 - Para tareas en background
• shared_preferences: ^2.2.2 - Para persistir configuración

📝 Configuración Android Requerida

Agregar en android/app/src/main/AndroidManifest.xml:

<uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED"/>

⚠️ Limitaciones

• Solo Android: iOS tiene restricciones más estrictas para background tasks
• Intervalo mínimo: 15 minutos (limitación de Android WorkManager)
• Batería: Android puede demorar la ejecución para optimizar batería

📚 Documentación

• README.md actualizado con sección completa de Background Sync
• Ejemplos de configuración y uso
• Notas sobre logout y limpieza

✨ Nuevas Características

Sincronización Automática

• Sincronización Periódica: Se ejecuta automáticamente cada 10 minutos cuando hay conexión a internet
• Sincronización al Reconectar: Se ejecuta automáticamente cuando se detecta que la conexión a internet se ha restaurado (de offline a online)
• Sin Configuración Necesaria: Funciona automáticamente una vez que se crea el primer OnlineOfflineManager
• Intervalo Configurable: El intervalo de sincronización se puede ajustar en GlobalConfig.syncMinutes (por defecto 10 minutos)

Detalles Técnicos

• Timer periódico que ejecuta syncAll() cada 10 minutos cuando hay internet
• Listener de conectividad que detecta cambios de estado de red
• Sincronización automática al detectar reconexión (transición de offline a online)
• Limpieza automática de recursos cuando no hay managers activos

📝 Documentación

• Documentación actualizada en README.md y README_SUPER_SIMPLE.md con información sobre sincronización automática
• Ejemplos de uso de la sincronización automática agregados

🔧 Cambios Internos

• GlobalConfig.syncMinutes cambiado de 5 a 10 minutos por defecto
• Agregado sistema de auto-sync con timer y listener de conectividad en OnlineOfflineManager
• Método disposeAutoSync() agregado para limpieza de recursos

🚀 MAJOR RELEASE - API Simplificada

Esta versión es una reescritura completa enfocada en simplicidad extrema.

⚠️ BREAKING CHANGES

GlobalConfig Simplificado

// ANTES (muchos parámetros)
GlobalConfig.init(
  baseUrl: 'https://api.com',
  token: 'tu-token',
  syncMinutes: 5,
  useIncrementalSync: true,
  pageSize: 25,
  lastModifiedField: 'updated_at',
  syncOnReconnect: true,
  maxLocalRecords: 1000,
  maxDaysToKeep: 7,
  maxPagesPerSync: 10,
  syncTimeoutMinutes: 30,
);

// DESPUÉS (solo 2 parámetros)
GlobalConfig.init(
  baseUrl: 'https://api.com',
  token: 'tu-token',
);

API del Manager Simplificada

// ANTES
final datos = await manager.getAll();  // Sincronizaba automáticamente (lento)
await manager.sync();
await manager.forceSync();
await manager.syncNow();
await manager.getSync();
await manager.getLocal();

// DESPUÉS
final datos = await manager.get();     // Siempre local (instantáneo)
await OnlineOfflineManager.syncAll();  // Un solo método para sincronizar

✨ Nueva API Super Simple

Métodos de Instancia

Métodos Estáticos

✨ Nuevas Características

Ver Estado de Sincronización

// Obtener todo junto
final data = await manager.getFullData();
print('Total: ${data.total}');
print('Sincronizados: ${data.syncedCount}');
print('Pendientes: ${data.pendingCount}');

// Acceder a los datos
for (final item in data.synced) { ... }
for (final item in data.pending) { ... }

Debug Info

await OnlineOfflineManager.debugInfo();
// Imprime info detallada de todos los managers y boxes

Estado Global

final estados = await OnlineOfflineManager.getAllSyncInfo();
for (final entry in estados.entries) {
  print('${entry.key}: ${entry.value.synced}/${entry.value.total}');
}

🗑️ Eliminado

• SyncConfig - Ya no se necesita
• getAll() - Reemplazado por get()
• getSync() / getLocal() - Reemplazados por getSynced() / getPending()
• sync(), forceSync(), syncNow() - Reemplazados por syncAll()
• syncAllManagers() - Reemplazado por syncAll()
• Sincronización automática en get() - Ahora es manual con syncAll()
• Parámetros de configuración avanzados en GlobalConfig

📝 Filosofía de la Nueva Versión

1. get() siempre es instantáneo - Lee datos locales sin esperar
2. El usuario decide cuándo sincronizar - Llamando a syncAll()
3. Configuración mínima - Solo baseUrl y token
4. Una forma de hacer las cosas - Sin métodos redundantes

Nuevas características:

• Sincronización ultra-inteligente con verificación previa
• Prevención y limpieza automática de duplicados
• Optimizaciones de rendimiento con límites de seguridad
• Sincronización manual vs automática diferenciada

Mejoras técnicas:

• Métodos separados para sincronización manual y automática
• Configuraciones avanzadas: maxPagesPerSync, syncTimeoutMinutes
• Logs detallados con estadísticas de procesamiento
• Detección de páginas vacías para evitar descargas innecesarias

Correcciones:

• Sincronización manual ahora siempre sincroniza
• Prevención automática de duplicados
• Mapeo correcto entre IDs y claves de almacenamiento
• Comportamiento consistente en todos los métodos manuales

Nuevos métodos:

• cleanDuplicates() para limpieza manual de duplicados
• Configuraciones recomendadas por tipo de aplicación
• Logs informativos para mejor debugging

Beneficios:

• UI más limpia sin registros duplicados
• Sincronización más rápida y eficiente
• Mejor experiencia de usuario
• Configuración flexible para diferentes tipos de apps

🚀 MAJOR UPDATE - Ultra-Smart Sync & Duplicate Prevention

Esta versión introduce sincronización ultra-inteligente y prevención de duplicados para una experiencia de sincronización perfecta.

✨ Nuevas Características Principales

🧠 Sincronización Ultra-Inteligente

• Verificación Previa: Hace una consulta pequeña para verificar si hay cambios
• Comparación Local: Compara registros existentes con los del servidor
• Procesamiento Selectivo: Solo procesa registros nuevos o modificados
• Logs Detallados: Muestra estadísticas de registros procesados

🧹 Prevención y Limpieza de Duplicados

• Detección Automática: Identifica registros duplicados basándose en ID
• Limpieza Automática: Se ejecuta después de cada sincronización incremental
• Limpieza Manual: Método cleanDuplicates() para limpieza manual
• Logs Informativos: Muestra cuántos duplicados se encontraron y eliminaron

⚡ Optimizaciones de Rendimiento

• Límites de Seguridad: Máximo 10 páginas por sincronización (configurable)
• Detección de Páginas Vacías: Se detiene si encuentra 2 páginas consecutivas vacías
• Timeout Inteligente: Usa descarga completa si han pasado más de 30 minutos
• Configuraciones Avanzadas: maxPagesPerSync, syncTimeoutMinutes

🔧 Mejoras Técnicas

Sincronización Manual vs Automática

• Sincronización Automática: Verifica tiempo transcurrido antes de sincronizar
• Sincronización Manual: Siempre sincroniza sin verificar tiempo
• Métodos Separados: _downloadFromServer() vs _downloadFromServerManual()
• Comportamiento Consistente: Todos los métodos manuales funcionan igual

Nuevas Configuraciones

GlobalConfig.init(
  baseUrl: 'https://tu-api.com',
  token: 'tu-token',
  syncMinutes: 15, // Sincronizar cada 15 minutos
  maxPagesPerSync: 5, // Máximo 5 páginas por sincronización
  syncTimeoutMinutes: 30, // Usar descarga completa si han pasado más de 30 minutos
  pageSize: 50, // Páginas más grandes para menos requests
);

📊 Nuevos Métodos

cleanDuplicates() - Limpieza de Duplicados

// Limpiar duplicados manualmente
await manager.cleanDuplicates();

Configuraciones Recomendadas por Tipo de App

// 📱 Para aplicaciones móviles
GlobalConfig.init(
  syncMinutes: 15,
  maxPagesPerSync: 3,
  syncTimeoutMinutes: 30,
  pageSize: 50,
);

// 💻 Para aplicaciones web
GlobalConfig.init(
  syncMinutes: 5,
  maxPagesPerSync: 10,
  syncTimeoutMinutes: 15,
  pageSize: 25,
);

// 🏢 Para aplicaciones empresariales
GlobalConfig.init(
  syncMinutes: 30,
  maxPagesPerSync: 20,
  syncTimeoutMinutes: 60,
  pageSize: 100,
);

🎯 Casos de Uso Optimizados

Sincronización Inteligente

• Primera sincronización: Descarga completa (normal)
• Sincronizaciones posteriores:
  • Verifica si hay cambios antes de descargar
  • Solo procesa registros nuevos o modificados
  • Muestra estadísticas detalladas
  • Es mucho más rápida y eficiente

Prevención de Duplicados

• Limpieza automática: Los duplicados se eliminan automáticamente
• Mejor detección: Los registros existentes se actualizan correctamente
• UI limpia: No más registros multiplicados en la interfaz
• Control manual: Puedes limpiar duplicados cuando necesites

🐛 Correcciones Importantes

Sincronización Manual

• ✅ Comportamiento Consistente: Todos los métodos manuales funcionan igual
• ✅ Sin Verificaciones de Tiempo: La sincronización manual siempre sincroniza
• ✅ Logs Claros: Sabes exactamente qué tipo de sincronización se está ejecutando
• ✅ Comportamiento Esperado: La sincronización manual funciona como el usuario espera

Prevención de Duplicados

• ✅ Limpieza Automática: Los duplicados se eliminan automáticamente
• ✅ Mejor Mapeo: Mapeo correcto entre IDs y claves de almacenamiento
• ✅ Actualización Correcta: Los registros existentes se actualizan usando la clave correcta
• ✅ Prevención de Creación: Evita crear nuevos registros cuando ya existen

📈 Beneficios de Rendimiento

Antes (v2.1.0)

🔄 Sincronización manual no sincronizaba
🔄 Registros se multiplicaban en la interfaz
🔄 Descargas masivas en cada reinicio

Después (v2.2.0)

🧠 Sincronización ultra-inteligente
🧹 Limpieza automática de duplicados
⚡ Sincronización manual siempre funciona
📊 Logs detallados con estadísticas

🔄 Migración desde v2.1.0

Sin Cambios Requeridos

// ✅ Tu código actual funciona sin cambios
final manager = OnlineOfflineManager(
  boxName: 'datos',
  endpoint: 'https://api.ejemplo.com/datos',
);

Optimización Opcional

// 🚀 NUEVO: Agregar configuraciones para mejor rendimiento
GlobalConfig.init(
  baseUrl: 'https://tu-api.com',
  token: 'tu-token',
  maxPagesPerSync: 5, // Evitar descargas masivas
  syncTimeoutMinutes: 30, // Usar descarga completa cuando sea necesario
);

// 🚀 NUEVO: Limpiar duplicados si es necesario
await manager.cleanDuplicates();

🎉 Ejemplos de Uso Optimizado

Sistema de Reportes Optimizado

class ReportService {
  static final manager = OnlineOfflineManager(
    boxName: 'reports',
    endpoint: 'harvest-delivery',
  );
  
  // Obtener reportes con sincronización inteligente
  static Future<List<Report>> getReports() async {
    final data = await manager.getAll(); // Sincronización automática inteligente
    return data.map((item) => Report.fromJson(item)).toList();
  }
  
  // Sincronización manual cuando sea necesario
  static Future<void> refreshReports() async {
    await manager.sync(); // Siempre sincroniza
  }
  
  // Limpiar duplicados si es necesario
  static Future<void> cleanupDuplicates() async {
    await manager.cleanDuplicates();
  }
}

📚 Nueva Documentación

Guías de Optimización

• Configuración Optimizada: Guía para evitar descargas masivas
• Manejo de Duplicados: Cómo prevenir y limpiar duplicados
• Sincronización Manual vs Automática: Diferencias y cuándo usar cada una
• Configuraciones Recomendadas: Por tipo de aplicación

🎯 Beneficios de la v2.2.0

Para Desarrolladores

• Sincronización Inteligente: Evita descargas innecesarias
• Prevención de Duplicados: No más registros multiplicados
• Configuración Flexible: Adaptable a diferentes tipos de apps
• Logs Detallados: Mejor debugging y monitoreo

Para Usuarios Finales

• UI Más Limpia: No más registros duplicados
• Sincronización Más Rápida: Solo descarga cuando es necesario
• Mejor Experiencia: Sincronización manual funciona como esperado
• Datos Consistentes: Prevención automática de duplicados

• Sincronización inteligente optimizada con caché
• Nuevas configuraciones: SyncConfig.frequent, occasional, rare, manual
• Nuevos métodos: getAllFast(), getAllWithSync(), forceSync()
• Timer automático de sincronización
• Logs optimizados (solo errores críticos)
• Documentación completa de optimización
• CacheManager inteligente con timestamps persistentes
• Hasta 20x más rápido para datos en caché

🚀 MAJOR UPDATE - Smart Sync Optimization & Performance Boost

Esta versión introduce sincronización inteligente optimizada y configuraciones de rendimiento para una experiencia de desarrollo aún mejor.

✨ Nuevas Características Principales

⚡ Sincronización Inteligente Optimizada

• Cache Inteligente: Sistema de caché con timestamps para evitar sincronizaciones innecesarias
• Configuraciones Predefinidas: SyncConfig.frequent, SyncConfig.occasional, SyncConfig.rare, SyncConfig.manual
• Timer Automático: Sincronización automática basada en intervalos configurables
• Rendimiento Mejorado: Hasta 20x más rápido para datos en caché

🎯 Nuevas Configuraciones de Sincronización

SyncConfig.frequent - Para datos que cambian frecuentemente

final manager = OnlineOfflineManager(
  boxName: 'messages',
  endpoint: 'https://api.ejemplo.com/messages',
  syncConfig: SyncConfig.frequent, // Sincroniza cada minuto
);

SyncConfig.occasional - Para datos que cambian ocasionalmente (RECOMENDADO)

final manager = OnlineOfflineManager(
  boxName: 'seasons',
  endpoint: 'https://api.ejemplo.com/seasons',
  syncConfig: SyncConfig.occasional, // Sincroniza cada 15 minutos
);

SyncConfig.rare - Para datos que cambian raramente

final manager = OnlineOfflineManager(
  boxName: 'config',
  endpoint: 'https://api.ejemplo.com/config',
  syncConfig: SyncConfig.rare, // Sincroniza cada hora
);

SyncConfig.manual - Para sincronización manual

final manager = OnlineOfflineManager(
  boxName: 'reports',
  endpoint: 'https://api.ejemplo.com/reports',
  syncConfig: SyncConfig.manual, // Solo sincroniza manualmente
);

🚀 Nuevos Métodos Optimizados

getAllFast() - Acceso rápido sin sincronización

// ⚡ RÁPIDO - Sin sincronización automática
final data = await manager.getAllFast();

getAllWithSync() - Sincronización inteligente

// ⚡ INTELIGENTE - Sincroniza solo si es necesario
final data = await manager.getAllWithSync();

forceSync() - Sincronización forzada

// 🔄 FORZADA - Siempre sincroniza
await manager.forceSync();

🔧 Mejoras Técnicas

CacheManager Inteligente

• Timestamps Persistentes: Caché que persiste entre sesiones usando Hive
• Verificación Automática: Detecta automáticamente si necesita sincronizar
• Configuración Flexible: Intervalos personalizables por tipo de datos

Timer de Sincronización Automática

• Timer Inteligente: Se ejecuta automáticamente según la configuración
• Solo con Conexión: Se activa únicamente cuando hay internet
• Gestión de Recursos: Se cancela automáticamente al cerrar

Logs Optimizados

• Solo Errores Críticos: Eliminados logs innecesarios para mejor rendimiento
• Debugging Efectivo: Mantiene información esencial para errores
• Código Más Limpio: Librería más profesional y silenciosa

📚 Nueva Documentación

Guías de Optimización

• OPTIMIZATION_GUIDE.md: Guía completa de optimización de rendimiento
• CLEANUP_SUMMARY.md: Resumen de limpieza de logs
• Ejemplos Prácticos: Casos de uso optimizados para diferentes tipos de datos

Mejores Prácticas

// 🎯 Para datos que cambian ocasionalmente (temporadas, categorías)
final seasonsManager = OnlineOfflineManager(
  boxName: 'seasons',
  endpoint: 'https://api.ejemplo.com/seasons',
  syncConfig: SyncConfig.occasional, // Sincroniza cada 15 minutos
);

// Uso normal - MUY RÁPIDO
final seasons = await seasonsManager.getAllFast();

// Solo cuando necesites datos frescos
if (needsFreshData(seasons)) {
  await seasonsManager.forceSync();
  final freshSeasons = await seasonsManager.getAllFast();
}

🎯 Casos de Uso Optimizados

Datos Frecuentes (Mensajes, Notificaciones)

• Configuración: SyncConfig.frequent
• Método: getAllWithSync()
• Resultado: Sincronización cada minuto automáticamente

Datos Ocasionales (Temporadas, Categorías)

• Configuración: SyncConfig.occasional
• Método: getAllFast() + forceSync() cuando sea necesario
• Resultado: Hasta 20x más rápido, sincronización inteligente

Datos Raros (Configuración, Usuarios)

• Configuración: SyncConfig.rare
• Método: getAllFast() + sincronización manual
• Resultado: Máximo rendimiento, control total

Datos Manuales (Reportes, Estadísticas)

• Configuración: SyncConfig.manual
• Método: getAllFast() + forceSync() solo cuando sea necesario
• Resultado: Control completo sobre cuándo sincronizar

⚡ Beneficios de Rendimiento

Antes (v2.0.0)

🔄 Sincronizando antes de obtener datos...
🔄 Iniciando sincronización automática...
📥 Descargando datos del servidor...
✅ Descargados 9 registros
✅ Sincronización completada

Tiempo: ~2-3 segundos por consulta

Después (v2.1.0)

⚡ Usando datos en caché (sincronización omitida)

Tiempo: ~50-100ms por consulta

🐛 Correcciones Importantes

Sincronización Optimizada

• ✅ Cache Inteligente: Evita sincronizaciones innecesarias
• ✅ Timer Automático: Sincronización programada eficiente
• ✅ Configuración Flexible: Diferentes estrategias por tipo de datos
• ✅ Logs Limpios: Solo errores críticos, mejor rendimiento

Gestión de Recursos

• ✅ Timer Management: Cancelación automática de timers
• ✅ Memory Optimization: Mejor gestión de memoria
• ✅ Error Handling: Manejo robusto de errores silencioso

🔄 Migración desde v2.0.0

Sin Cambios Requeridos

// ✅ Tu código actual funciona sin cambios
final manager = OnlineOfflineManager(
  boxName: 'seasons',
  endpoint: 'https://api.ejemplo.com/seasons',
  // syncConfig: SyncConfig.occasional, // NUEVO: Agregar para optimización
);

Optimización Opcional

// 🚀 NUEVO: Agregar configuración para mejor rendimiento
final manager = OnlineOfflineManager(
  boxName: 'seasons',
  endpoint: 'https://api.ejemplo.com/seasons',
  syncConfig: SyncConfig.occasional, // Agregar esta línea
);

// 🚀 NUEVO: Usar getAllFast() para mejor rendimiento
final data = await manager.getAllFast(); // En lugar de getAllWithSync()

📈 Métricas de Rendimiento

Mejoras Cuantificables

• Velocidad: Hasta 20x más rápido para datos en caché
• Consumo de Datos: Reducido en 80% para datos ocasionales
• Batería: Menor consumo por menos operaciones de red
• UX: Carga instantánea de datos locales

Casos de Uso Reales

• Temporadas: De 2-3 segundos a 50-100ms
• Categorías: Sincronización solo cuando es necesario
• Configuración: Carga instantánea, sincronización manual
• Reportes: Control total sobre cuándo actualizar

🧪 Testing Actualizado

Nuevos Tests

• Cache Management: Tests para sistema de caché inteligente
• Sync Configurations: Tests para todas las configuraciones
• Timer Management: Tests para sincronización automática
• Performance Tests: Tests de rendimiento y optimización

🎉 Ejemplos de Uso Optimizado

Sistema de Temporadas Optimizado

class SeasonService {
  static final SeasonService _instance = SeasonService._internal();
  factory SeasonService() => _instance;
  SeasonService._internal();

  OnlineOfflineManager? _manager;
  bool _isInitialized = false;

  void initialize() {
    if (_isInitialized) return;

    _manager = OnlineOfflineManager(
      boxName: 'seasons',
      endpoint: 'apps/paletization/utilities/seasons',
      syncConfig: SyncConfig.occasional, // Optimizado para temporadas
    );
    _isInitialized = true;
  }

  Future<List<Season>> getAllSeasons() async {
    if (!_isInitialized) initialize();
    if (_manager == null) throw Exception('SeasonService no inicializado');

    // Usar getAllWithSync() para sincronización inteligente
    final rawData = await _manager!.getAllWithSync();
    return rawData
        .map((json) => Season.fromJson(json))
        .where((season) => season.isActive)
        .toList();
  }
}

🎯 Beneficios de la v2.1.0

Para Desarrolladores

• Configuración Simple: Una línea para optimizar cualquier tipo de datos
• Múltiples Estrategias: Flexible para diferentes casos de uso
• Logs Limpios: Solo información esencial, mejor debugging
• Documentación Completa: Guías paso a paso para optimización

Para Usuarios Finales

• UI Más Rápida: Carga instantánea de datos locales
• Menos Esperas: Sincronización inteligente solo cuando es necesario
• Mejor Offline: Datos siempre disponibles localmente
• Experiencia Fluida: Sin interrupciones por sincronizaciones innecesarias

🚀 MAJOR RELEASE - Smart API Response Detection & Enhanced Data Access

Esta versión introduce detección automática de respuestas anidadas y nuevos métodos de acceso a datos para una experiencia de desarrollo aún mejor.

✨ Nuevas Características Principales

🌐 Detección Automática de Respuestas Anidadas

• Detección Inteligente: Reconoce automáticamente respuestas con formato {data: [...], total: N}
• Extracción Automática: Extrae el array data sin configuración adicional
• Compatibilidad Universal: Funciona con respuestas simples y anidadas
• Logs Informativos: Muestra metadatos útiles como total y page

// ✨ AHORA FUNCIONA AUTOMÁTICAMENTE
// Respuesta del servidor: {data: [...], total: 100}
// getFromServer() retorna directamente: [...]
final datos = await manager.getFromServer();

🚀 Nuevos Métodos de Acceso a Datos

getFromServer() - Datos Frescos del Servidor

// Obtiene datos directamente del servidor (requiere internet)
final datosFrescos = await manager.getFromServer();

getAllWithSync() - Sincronización Inteligente

// Sincroniza primero, luego retorna datos actualizados
final datosActualizados = await manager.getAllWithSync();

📊 Procesamiento Mejorado de APIs

• Múltiples Formatos: Soporte para APIs REST estándar
• Respuestas Anidadas: {data: [...], total: N, page: 1}
• Respuestas Simples: [{...}, {...}]
• Objetos Únicos: {id: 1, name: "..."}

🔧 Mejoras Técnicas

ApiClient Mejorado

• Extracción Automática: Método _extractNestedData() para respuestas anidadas
• Mejor Logging: Información detallada sobre el procesamiento
• Manejo de Errores: Gestión robusta de diferentes formatos de respuesta

SyncService Expandido

• Nuevo Método: getDirectFromServer() para acceso directo al servidor
• Mejor Procesamiento: Manejo inteligente de tipos de datos
• Error Handling: Mensajes de error más descriptivos

📚 Documentación Completa Renovada

README Completamente Reescrito

• Guía Paso a Paso: Desde instalación hasta uso avanzado
• Ejemplos Reales: Casos de uso del mundo real
• Mejores Prácticas: Cuándo usar cada método
• API Reference: Documentación completa de todos los métodos

Nuevas Guías

• Guía de Uso: ¿Cuándo usar getAll() vs getFromServer() vs getAllWithSync()?
• Ejemplos Completos: Lista de tareas, sistema de comentarios
• Testing Guide: Cómo testear tu aplicación
• Manejo de Errores: Estrategias robustas de error handling

🎯 Nuevas Mejores Prácticas

Estrategia de Carga de Datos

// 🚀 Carga rápida inicial + sincronización background
Future<void> _cargarDatos() async {
  // 1. Cargar datos locales primero (rápido)
  final datosLocales = await manager.getAll();
  setState(() { datos = datosLocales; });
  
  // 2. Sincronizar en background
  if (manager.isOnline) {
    final datosActualizados = await manager.getAllWithSync();
    setState(() { datos = datosActualizados; });
  }
}

Pull to Refresh Optimizado

// 🔄 Refresh inteligente con datos frescos
Future<void> _onRefresh() async {
  try {
    final datosFrescos = await manager.getFromServer();
    setState(() { datos = datosFrescos; });
  } catch (e) {
    // Mantener datos actuales en caso de error
    _mostrarError('Error actualizando datos');
  }
}

🐛 Correcciones Importantes

Procesamiento de Respuestas

• ✅ Respuestas Anidadas: Ahora se procesan correctamente
• ✅ Múltiples Formatos: Soporte universal para diferentes APIs
• ✅ Error Handling: Mejor manejo de respuestas malformadas

Sincronización

• ✅ Sync Automático: Mejorada la confiabilidad
• ✅ Conectividad: Mejor detección de estado de red
• ✅ Data Consistency: Consistencia mejorada entre local y servidor

🔄 Breaking Changes (Mínimos)

ApiClient

• GET Requests: Ahora extraen automáticamente datos anidados
• Backward Compatible: El 99% del código existente sigue funcionando
• Migration Path: Actualización transparente en la mayoría de casos

⚡ Performance

Optimizaciones

• Carga Más Rápida: getAll() optimizado para UI
• Network Efficiency: Mejor uso de requests de red
• Memory Usage: Gestión de memoria mejorada

🧪 Testing Actualizado

Nuevos Tests

• Response Processing: Tests para detección de respuestas anidadas
• New Methods: Cobertura completa de getFromServer() y getAllWithSync()
• Error Scenarios: Tests robustos de manejo de errores

🎉 Ejemplos de Uso

Sistema de Tareas Completo

class TaskManager {
  static final manager = OnlineOfflineManager(
    boxName: 'tasks',
    endpoint: 'tasks',
  );
  
  // Cargar tareas con sincronización inteligente
  static Future<List<Task>> getTasks() async {
    final data = await manager.getAllWithSync();
    return data.map((item) => Task.fromMap(item)).toList();
  }
  
  // Refrescar desde servidor
  static Future<List<Task>> refreshTasks() async {
    final data = await manager.getFromServer();
    return data.map((item) => Task.fromMap(item)).toList();
  }
}

📈 Beneficios de la v2.0.0

Para Desarrolladores

• Menos Código: Detección automática reduce boilerplate
• Más Flexible: Múltiples estrategias de acceso a datos
• Mejor DX: Documentación completa y ejemplos reales

Para Usuarios Finales

• UI Más Rápida: Carga inicial optimizada
• Mejor Offline: Sincronización más inteligente
• Datos Frescos: Acceso fácil a datos actualizados del servidor

� Corrección Crítica

• ConnectivityService: Corregido para funcionar correctamente en dispositivos reales
• Detección de Test: Mejorada la detección de entornos de test vs dispositivos reales
• Conectividad Real: Ahora detecta correctamente la conectividad en emuladores y dispositivos físicos

🔧 Mejoras y Correcciones

• ConnectivityService: Mejorado para funcionar en entornos de test
• Tests: Todos los 36 tests pasan exitosamente
• Documentación: README actualizado y más directo
• Inicialización Automática: Hive se inicializa automáticamente
• Compatibilidad: Mejor compatibilidad con diferentes entornos

🚀 Primera Versión Pública

• Nombre del paquete: betuko_offline_sync - Librería Flutter offline-first
• LICENSE: Archivo de licencia MIT agregado
• Validación completa: Todos los errores de pub.dev resueltos
• Documentación: README completo con ejemplos prácticos
• Tests: 36 tests pasando exitosamente
• Arquitectura simplificada: Fácil de usar y mantener

✨ Agregado

• OnlineOfflineManager: Gestor principal simplificado
• LocalStorageService: Almacenamiento local automático con Hive
• ConnectivityService: Detección de conectividad en tiempo real
• SyncService: Sincronización automática bidireccional
• ApiClient: Cliente HTTP integrado para comunicación con servidor
• GlobalConfig: Configuración global de baseUrl y token
• Streams Reactivos: UI que se actualiza automáticamente