Aller au contenu

ADR-002 — Offline-first avec deux files de synchronisation

Statut

Accepté

Date

2026-07-08 (documenté rétroactivement)

Contexte

Feelbat est utilisé sur le terrain — chantiers, structures isolées, sous-sols — où la connectivité est peu fiable ou absente. Les techniciens de terrain doivent pouvoir lire les données et enregistrer des opérations sur capteur hors ligne, et voir ce travail synchronisé au retour de la connectivité. Les mesures de capteur récupérées via BLE peuvent être volumineuses et ne doivent pas être perdues.

Décision

Adopter un modèle offline-first piloté par un unique flag Redux online.

  • Lectures : online bascule la fetchPolicy Apollo entre cache-and-network et cache-only ; le cache est persisté vers AsyncStorage (apollo3-cache-persist). Le passage hors ligne est gouverné par usePreloadQueries, qui pré-charge d'abord les données nécessaires.
  • Écritures : deux files complémentaires :
  • File Apollo générique — trackerLink (src/utils/trackerLink.ts) + apollo-link-queue + apollo-link-serialize. Les mutations marquées context.tracked sont sérialisées dans le duck trackedQueries et rejouées à la reconnexion.
  • File de sync métier — le duck syncManager : une file spécifique aux capteurs pour les lots de mesures (sensorsToSync, avec un SyncStatus) et les mutations typées capteur/projet (syncableMutations). Les payloads de mesure sont stockés en fichiers JSON sur disque (react-native-fs), pas dans le cache Apollo.

HandleSyncMutationOnline (toujours monté) surveille NetInfo et, à la reconnexion, lance syncMeasures() puis rejoue les mutations en file. L'écran SyncManager et le SyncManagerButton donnent aux utilisateurs de la visibilité et un contrôle manuel.

Conséquences

Positives

  • Capacité complète de lecture/écriture hors ligne ; rien n'est perdu.
  • Les gros lots de mesures sont gérés hors du cache normalisé (stockage fichier) — évite le gonflement du cache.
  • Les utilisateurs voient et peuvent relancer les syncs en attente.

Négatives / Compromis

  • Deux files d'écriture parallèles aux mécaniques différentes — une vraie source de complexité ; les contributeurs doivent savoir quel chemin emprunte une mutation donnée.
  • La bascule manuelle online/offline ajoute de la surface UX.
  • Les cas limites de sérialisation (circular-json) et l'ordre de rejeu demandent de la vigilance.

Alternatives considérées

  • Realm comme stockage offline — des schémas ont été définis (src/utils/realm/models/) mais jamais branchés ; l'application utilise cache-persist Apollo + fichiers JSON à la place. Les modèles Realm restent inutilisés (voir architecture.md).
  • cache-persist Apollo seul — insuffisant pour les gros lots de mesures BLE et pour l'UX de sync spécifique au métier, d'où la seconde file.