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
- 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.
- É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.
- 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_idsur 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 oupending_queue_id). - Suppression : si la ligne est encore uniquement locale (
pending_queue_idou 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é i18nreports.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 SQLiteaux_screens_box_snapshotdanspos_sync_cache_v1.db). - En erreur réseau,
getManagerUsers,getManagerCustomers,getManagerDebtsetgetManagerRoles(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 viasyncPendingCustomerCreates()danssyncAllOffline()(étape 7). - Paiement dette hors ligne : file
debtPayQueue.ts; montants reste / payé / statut mis à jour localement (managerDebtsOfflineMerge.ts) ; badge À synchroniser ; sync viasyncPendingDebtPays()(étape 8). - Les écrans affichent la bannière données en cache (
reports.cachedData) lorsquefromCacheest présent.
Abonnement & écran verrou
- Dernier statut
/subscription/statuspersisté danssubscriptionStatusCache.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.