Offline and sync

1/// Zone data is static (satellite imagery from specific date).2/// Unlike weather, we don't consider zone cache "stale" - it's valid until3/// we regenerate zones.db with newer satellite data.4/// 5/// However, we may want to refresh after major app updates.6bool get isExpired {7  // Expire after 1 year to allow for data updates8  return DateTime.now().toUtc().difference(fetchedAt).inDays > 365;9}

1/// Get zone data for an H3 index, using cache-first strategy.2///3/// Returns:4/// - [ZoneData] from cache or remote API5/// - [pristineDarkSky] if not found in database (dark sky location!)6Future<ZoneData> getZoneData(BigInt h3Index) async {7  final String h3Hex = h3Index.toRadixString(16);8  final String cacheKey = '$_keyPrefix$h3Hex';910  // 1. Check cache first11  final ZoneCacheEntry? cached = _cache.get(cacheKey);12  if (cached != null && !cached.isExpired) {13    debugPrint('Zone cache hit for $h3Hex');14    return ZoneData(15      astrZone: cached.astrZone,16      ratio: cached.ratio,17      sqm: cached.sqm,18    );19  }2021  // 2. Cache miss — fetch from remote D1 API22  debugPrint('Zone cache miss for $h3Hex, fetching from remote...');23  final ZoneData? remoteData = await _remote.getZoneData(h3Index);2425  if (remoteData != null) {26    _cacheZoneData(cacheKey, h3Hex, remoteData);27    return remoteData;28  }2930  // 3. Remote failed - check if we have stale cache31  if (cached != null) {32    debugPrint('Remote failed, using expired cache for $h3Hex');33    return ZoneData(34      astrZone: cached.astrZone,35      ratio: cached.ratio,36      sqm: cached.sqm,37    );38  }3940  // 4. Not in database = pristine dark sky location41  debugPrint('$h3Hex not in lit-areas DB, returning pristine dark sky');42  return pristineDarkSky;43}

1/// Check if cache is stale (>24 hours old).2/// Per FR-09: Retain expired data until replacement succeeds.3bool get isStale => DateTime.now().toUtc().difference(fetchedAt).inHours > 24;

1/// Generates a cache key from H3 index and date.2///3/// Date is normalized to midnight UTC to ensure consistent keys4/// regardless of timezone or time of day.5static String generate(String h3Index, DateTime date) {6  final normalizedDate = DateTime.utc(date.year, date.month, date.day);7  final dateStr = _formatDate(normalizedDate);8  return 'weather_${h3Index}_$dateStr';9}

1/// Generates a daily forecast cache key.2///3/// Format: `weather_{h3Index}_daily_{YYYY-MM-DD}`4/// Used for 7-day individual forecast caching (Story 3.2).5static String generateDaily(String h3Index, DateTime date) {6  final normalizedDate = DateTime.utc(date.year, date.month, date.day);7  final dateStr = _formatDate(normalizedDate);8  return 'weather_${h3Index}_daily_$dateStr';9}

1/// Prunes cache entries older than "Today 09:00 AM" (device local time).2///3/// FR-10: System must prune weather data older than "Today 09:00 AM".4///5/// Returns the number of entries deleted.6Future<int> pruneOldEntries() async {7  if (_cache.isEmpty) return 0;89  final DateTime now = DateTime.now();10  final DateTime threshold = DateTime(11    now.year,12    now.month,13    now.day,14    9, // 09:00 AM15  );1617  int deletedCount = 0;18  final List<dynamic> keysToDelete = <dynamic>[];1920  // Collect keys to delete21  for (final dynamic key in _cache.keys) {22    final WeatherCacheEntry? entry = _cache.get(key);23    if (entry == null) continue;2425    // Check if entry date is before threshold26    final DateTime entryDate = DateTime(27      entry.date.year,28      entry.date.month,29      entry.date.day,30    );3132    if (entryDate.isBefore(threshold)) {33      keysToDelete.add(key);34    }35  }3637  // Delete in batch38  for (final dynamic key in keysToDelete) {39    try {40      await _cache.delete(key);41      deletedCount++;42    } catch (e, st) {43      debugPrint('Failed to delete cache entry $key: $e');44      debugPrint('Stack trace: $st');45      // Continue with other deletions46    }47  }4849  if (deletedCount > 0) {50    debugPrint('WeatherCachePruningService: Pruned $deletedCount old entries');51  }5253  return deletedCount;54}

1/// Prefetches all data types for a single location.2///3/// Runs all fetches concurrently for speed. Each fetch independently4/// populates the cache via [CachedWeatherRepository] and [CachedZoneRepository].5///6/// Never throws — all errors are caught and logged silently.7Future<void> prefetchForLocation(GeoLocation location) async {8  debugPrint('Prefetch: Starting for ${location.name ?? 'unnamed'} '9      '(${location.latitude}, ${location.longitude})');1011  await Future.wait<void>(<Future<void>>[12    _prefetchCurrentWeather(location),13    _prefetchHourlyForecast(location),14    _prefetchDailyForecast(location),15    _prefetchZoneData(location),16  ]);1718  debugPrint('Prefetch: Completed for ${location.name ?? 'unnamed'}');19}

1/// Syncs weather for all active (non-stale) locations.2///3/// Active locations are:4/// - Pinned locations (always active, bypass staleness)5/// - Non-stale locations (lastViewed < 11 days ago)6///7/// Returns the number of locations successfully synced.8/// Never throws - all errors are caught and logged (NFR-04).9Future<int> syncActiveLocations() async {10  try {11    // Get all saved locations12    final Either<Failure, List<UserLocation>> result =13        await _locations.getAllLocations();1415    return await result.fold(16      (Failure failure) {17        // Silent failure - log but don't crash18        debugPrint('Background sync: Failed to load locations: $failure');19        return 0;20      },21      (List<UserLocation> locations) async {22        if (locations.isEmpty) {23          debugPrint('Background sync: No locations to sync');24          return 0;25        }2627        int syncedCount = 0;2829        // Prioritize pinned locations first (most important)30        final List<UserLocation> sortedLocations = <UserLocation>[31          ...locations.where((UserLocation loc) => loc.isPinned),32          ...locations.where((UserLocation loc) => !loc.isPinned),33        ];3435        for (final UserLocation location in sortedLocations) {36          // Skip stale locations (unless pinned)37          if (_shouldSkipLocation(location)) {38            debugPrint(39                'Background sync: Skipping stale location ${location.name}');40            continue;41          }4243          // Attempt to sync weather for this location44          final bool success = await _syncLocation(location);45          if (success) syncedCount++;4647          // Battery-conscious: Small delay between requests48          await Future<void>.delayed(const Duration(milliseconds: 500));49        }5051        debugPrint(52            'Background sync: Synced $syncedCount/${locations.length} locations');53        return syncedCount;54      },55    );56  } catch (e, st) {57    // NFR-04: Silent failure - log but don't crash58    debugPrint('Background sync: Unexpected error: $e');59    debugPrint('Stack trace: $st');60    return 0;61  }62}

1/// Determines if a location should be skipped during sync.2///3/// Skip if:4/// - NOT pinned AND stale (> 11 days since last view)5bool _shouldSkipLocation(UserLocation location) {6  // Pinned locations are NEVER skipped7  if (location.isPinned) return false;89  // Use the established staleness logic from Epic 210  return UserLocationsNotifier.isStale(location);11}

1/// Registers background sync with WorkManager.2///3/// Call this from main.dart during app initialization.4/// Safe to call multiple times - won't create duplicate tasks.5Future<void> initializeBackgroundSync() async {6  // BGTaskScheduler throws a native NSException on the iOS Simulator7  // that cannot be caught by Dart try-catch, causing a crash (SIGABRT).8  // Skip registration entirely on the simulator.9  if (Platform.isIOS) {10    final IosDeviceInfo deviceInfo = await DeviceInfoPlugin().iosInfo;11    if (!deviceInfo.isPhysicalDevice) {12      debugPrint('Background sync: Skipping on iOS Simulator');13      return;14    }15  }1617  try {18    await Workmanager().initialize(19      callbackDispatcher,20      isInDebugMode: kDebugMode,21    );2223    // Schedule periodic background sync (once per day)24    await Workmanager().registerPeriodicTask(25      kWeatherSyncTaskName,26      kWeatherSyncTaskKey,27      frequency: const Duration(hours: 24),28      constraints: Constraints(29        networkType: NetworkType.connected, // Require network30        requiresBatteryNotLow: true, // Skip if battery critical31      ),32      existingWorkPolicy: ExistingPeriodicWorkPolicy.keep, // Don't replace existing33    );3435    debugPrint('Background sync: WorkManager initialized');36  } catch (e) {37    // Silent fail - background sync is best-effort38    debugPrint('Background sync: Failed to initialize WorkManager: $e');39  }40}