geo/app/docs/CACHE-CLEANING-SYSTEM.md

🧹 Système de Nettoyage du Cache - GEOSECTOR

📋 Vue d'ensemble

Un système complet de nettoyage du cache a été implémenté dans l'application GEOSECTOR pour résoudre les problèmes de compatibilité lors des mises à jour de la structure des données Hive.

🎯 Problème résolu

Les testeurs rencontraient des problèmes au démarrage de l'application après une mise à jour modifiant la structure des boxes Hive, nécessitant un nettoyage manuel du cache du navigateur.

✨ Fonctionnalités implémentées

1. 🔄 Nettoyage automatique à chaque changement de version

• Détection automatique : Compare la version stockée avec la version actuelle
• Nettoyage sélectif : Supprime toutes les données SAUF pending_requests
• Web uniquement : Activé uniquement sur la plateforme web
• Transparent : S'exécute automatiquement au démarrage

2. 🔘 Bouton de nettoyage manuel

• Accessible à tous : Disponible dans tous les environnements (DEV/REC/PROD)
• Confirmation requise : Dialog de confirmation avant nettoyage
• Feedback visuel : Barre de progression et messages de statut
• Icône orange : Facilement identifiable avec l'icône cleaning_services

3. 📊 Logging détaillé

• Emojis descriptifs : Pour une lecture rapide des logs
• Étapes détaillées : Chaque opération est loggée
• Gestion d'erreurs : Capture et log toutes les erreurs
• Statistiques : Nombre de requêtes préservées, boxes nettoyées, etc.

🛠️ Détails techniques

Fichiers modifiés

• lib/presentation/auth/splash_page.dart : Logique principale du nettoyage
• lib/core/utils/html_stub.dart : Stub pour compatibilité multi-plateforme

Méthodes principales

_performSelectiveCleanup()

// Étapes du nettoyage :
1. Nettoyer le Service Worker (web)
2. Sauvegarder pending_requests
3. Fermer toutes les boxes
4. Supprimer les boxes du disque
5. Réinitialiser Hive
6. Restaurer pending_requests
7. Sauvegarder la nouvelle version

_checkVersionAndCleanIfNeeded()

// Logique de détection :
- Compare version stockée vs actuelle
- Si différente → nettoyage automatique
- Si première installation → sauvegarde version
- Si identique → pas de nettoyage

Boxes préservées

• pending_requests : TOUJOURS préservée (données critiques offline)

Boxes nettoyées

• user
• operations
• passages
• sectors
• membres
• amicale
• clients
• user_sector
• settings
• chat_rooms
• chat_messages

📝 Logs de debug

Exemple de log de nettoyage automatique

🔍 Vérification de version:
   Version stockée: 3.1.9
   Version actuelle: 3.2.0
🆕 NOUVELLE VERSION DÉTECTÉE !
   Migration de 3.1.9 vers 3.2.0
🧹 === DÉBUT DU NETTOYAGE DU CACHE === 🧹
📌 Type: AUTOMATIQUE
📱 Platform: WEB
📦 Version actuelle: 3.2.0
🔄 Nettoyage du Service Worker...
✅ Service Worker désenregistré
💾 Sauvegarde des requêtes en attente...
📊 5 requêtes en attente sauvegardées
🗑️ Nettoyage des boxes Hive...
✅ Box "user" supprimée
✅ Box "operations" supprimée
[...]
♻️ Restauration des requêtes en attente...
✅ 5 requêtes restaurées
💾 Version 3.2.0 sauvegardée
🎉 === NETTOYAGE TERMINÉ AVEC SUCCÈS === 🎉

Exemple de log de nettoyage manuel

👤 Utilisateur a demandé un nettoyage manuel
🧹 === DÉBUT DU NETTOYAGE DU CACHE === 🧹
📌 Type: MANUEL
[...]

🎨 Interface utilisateur

Indicateurs visuels pendant le nettoyage

• Barre de progression : Animée avec pourcentage
• Messages de statut :
  • "Nettoyage du cache en cours..."
  • "Fermeture des bases de données..."
  • "Nettoyage des données locales..."
  • "Réinitialisation de Hive..."
  • "Nettoyage terminé !"

Dialog de confirmation (nettoyage manuel)

Titre : "Nettoyer le cache ?"
Message : 
• Supprimer toutes les données locales
• Préserver les requêtes en attente
• Forcer le rechargement de l'application

[Annuler] [Nettoyer]

⚠️ Points d'attention

1. Ne JAMAIS supprimer pending_requests : Données critiques pour la synchronisation offline
2. Web uniquement : Le nettoyage automatique n'est actif que sur web
3. Test en DEV : Toujours tester les changements de structure en DEV avant REC/PROD
4. Version à incrémenter : Penser à incrémenter la version dans pubspec.yaml

🚀 Utilisation

Pour les développeurs

1. Modifier la structure Hive
2. Incrémenter la version dans pubspec.yaml
3. Déployer → Le nettoyage se fera automatiquement

Pour les testeurs

• Si problème : Cliquer sur "Nettoyer le cache" (bouton orange)
• Confirmer l'action
• L'app redémarre proprement

📈 Bénéfices

• ✅ Zéro intervention manuelle des testeurs
• ✅ Préservation des données critiques (requêtes offline)
• ✅ Transparence totale via les logs
• ✅ Fallback manuel si nécessaire
• ✅ Migration fluide entre versions