Offline POS mobile local-first

Lien isolé Accueil docs Formation
Mobile POS

Architecture local-first de l'app mobile : SQLite, queues, sync.

POS mobile — actions locales visibles sans synchronisation

Ce document décrit le comportement local-first de l’app React Native (pos-mobile) : l’interface et les caches SQLite reflètent immédiatement les actions utilisateur ; la synchronisation ne fait que pousser les opérations en attente vers le serveur et réconcilier les identifiants.


Principes

  1. Lecture UI : listes et écrans de détail lisent d’abord le cache SQLite (et la file d’opérations pour les brouillons non encore poussés), puis complètent ou remplacent par la réponse API quand le réseau est disponible.
  2. Écriture locale : création / suppression hors ligne met à jour cache + file ; pas d’obligation d’appel serveur pour annuler un brouillon qui n’y est pas encore.
  3. Sync : au succès d’une opération serveur, les entrées temporaires (ids négatifs, pending_queue_id, lignes liste/détail « brouillon ») sont retirées et remplacées par les données canoniques du serveur.

Produits & inventaire

  • Lorsqu’un nouveau produit est enregistré sans réseau (ou en erreur réseau gérée comme file), une entrée est ajoutée à la file de création produit et fusionnée dans le cache POS et le cache inventaire (ligne dérivée du formulaire, devise alignée sur le snapshot inventaire).
  • Après sync réussie, les lignes locales (id négatif) sont supprimées du cache et le produit serveur est fusionné (productCreateQueue).

Achats (liste, détail, suppression)

  • Après enqueue d’un nouvel achat, la liste et le détail hors ligne sont persistés (persistOfflinePurchaseDraftAfterQueue, pending_queue_id sur la ligne stockée).
  • Au chargement de la liste, les achats en attente sont fusionnés en tête de page 1 (mergePendingPurchasesIntoListPage) et une passe de réhydratation (ensurePendingPurchaseCreatesInListAndDetailCaches) couvre les cas (réinstallation, cache partiel).
  • Le détail résout d’abord un brouillon via getPendingPurchaseDetailIfExists (id stable négatif ou pending_queue_id).
  • Suppression : si la ligne est encore uniquement locale (pending_queue_id ou id négatif résolu), suppression sans API : retrait de la file + nettoyage caches liste/détail.

Rapports (ventes, achats, stock, caisse, marge)

  • Les endpoints de rapports enregistrent la dernière réponse réussie dans le même box AsyncStorage + SQLite (reportsCache.ts : ventes, achats, stock, grand livre caisse, marge).
  • En absence de réseau, si une entrée existe pour la même période (ou « dernier stock » pour le résumé stock), l’écran affiche ces données avec la mention données en cache (fromCache, clé i18n reports.cachedData).
  • Limite importante : les agrégats ne recalculent pas automatiquement les ventes / achats uniquement présents dans la file locale tant qu’ils n’ont pas été acceptés par le serveur et qu’un nouveau pull de rapport n’a pas été fait en ligne. Pour une période jamais consultée en ligne, il n’y a pas de snapshot serveur à montrer hors ligne.

Gestion (utilisateurs, clients, dettes, rôles)

  • Dernière réponse paginée / filtrée est persistée dans auxScreensOfflineCache.ts (AsyncStorage + table SQLite aux_screens_box_snapshot dans pos_sync_cache_v1.db).
  • En erreur réseau, getManagerUsers, getManagerCustomers, getManagerDebts et getManagerRoles (résultat { roles, fromCache? }) rejouent le snapshot correspondant aux mêmes paramètres (page, recherche, filtre retard, etc.).
  • Création client hors ligne : file customerCreateQueue.ts + lignes locales fusionnées en tête de la liste (customerLocalDrafts.ts, managerCustomersOfflineMerge.ts) ; badge À synchroniser sur l’écran Clients ; sync via syncPendingCustomerCreates() dans syncAllOffline() (étape 7).
  • Paiement dette hors ligne : file debtPayQueue.ts ; montants reste / payé / statut mis à jour localement (managerDebtsOfflineMerge.ts) ; badge À synchroniser ; sync via syncPendingDebtPays() (étape 8).
  • Les écrans affichent la bannière données en cache (reports.cachedData) lorsque fromCache est présent.

Abonnement & écran verrou

  • Dernier statut /subscription/status persisté dans subscriptionStatusCache.ts (même box auxiliaire SQLite).
  • Hors ligne : si le cache indique abonnement actif, l’app reste utilisable (pas de verrouillage à tort) avec les dernières capacités connues.
  • Si le cache indique expiré, l’écran Abonnement expiré s’affiche avec les infos en cache et un bouton Vérifier la connexion.
  • À la connexion, le statut issu de la réponse login est aussi mis en cache.

Caisse manuelle & graphiques caisse

  • Liste période (getCashBookManual), solde d’ouverture (getCashBookManualOpening) et agrégats graphiques (getCashBookManualChartAggregates) sont mis en cache avec la même mécanique auxiliaire.
  • Hors ligne : affichage du dernier jeu chargé en ligne pour la même clé (période + pagination + recherche pour la liste).

Paramètres (options caissier mobile)

  • getSettings() persiste la réponse complète sous la clé dédiée ; hors ligne, les interrupteurs caissier sont rechargés depuis ce snapshot (fromCache + bannière sur l’écran Paramètres).
  • Après une modification réussie via patchCashierMobileSettings, la bannière cache est retirée (données considérées comme à jour côté client).

Caisse POS (session)

  • getCashStatus() utilisait déjà cashCache ; l’écran Caisse affiche en plus la bannière cache lorsque la session affichée provient du dernier snapshot synchronisé.

Fichiers utiles (repères)

Zone Fichiers
Brouillons achats purchaseLocalDrafts.ts, purchasesOfflineCache.ts, purchaseQueue.ts
Brouillons produits productLocalDrafts.ts, productCreateQueue.ts
API liste/détail achats api.ts (getPurchasesList, getPurchaseDetail)
Inventaire / SQLite inventoryCache.ts, posSyncSqlite.ts
Rapports cache reportsCache.ts, api.ts (getReportSalesSummary, getReportPurchasesSummary, getReportStockSummary, getCashLedger, getReportProfitSummary)
Gestion + caisse manuelle + réglages snapshot auxScreensOfflineCache.ts, api.ts (getManagerUsers, getManagerCustomers, getManagerDebts, getManagerRoles, getCashBookManual, …), logout → clearAuxScreensOfflineCache
File création client customerCreateQueue.ts, customerLocalDrafts.ts, managerCustomersOfflineMerge.ts
File paiements dettes debtPayQueue.ts, managerDebtsOfflineMerge.ts
Cache abonnement subscriptionStatusCache.ts, getSubscriptionStatus, refreshSubscriptionContext

Dernière mise à jour : paiements dettes hors ligne + abonnement / verrou hors ligne.