Offline V1 — périmètre

Lien isolé Accueil docs Formation
Mobile POS

Première phase offline : périmètre fonctionnel et limites.

Périmètre « Mode hors ligne » v1 — ShopManager Pro

Objectif : poser un cadre produit et technique pour étendre le hors-ligne sans promettre une duplication complète du SaaS en local.


1) Parcours prioritaires (v1 — terrain)

Ces flux sont déjà partiellement couverts dans le code (IndexedDB + /api/sync + UI legacy). Le v1 consiste à les stabiliser, documenter et les compléter avant d’élargir.

Priorité Parcours Données à synchroniser (pull) Actions en file d’attente (push) Hors périmètre v1
P0 POS / vente Produits, variations, catégories, clients (utiles), stocks reflétés pos_sales, ventes, lignes, mouvements stock liés SFN / facturation fiscale obligatoire offline
P0 Inventaire / produits Idem catalogue CRUD produits/catégories, ajustements stock Import masse, médias lourds
P1 Clients & dettes Clients, dettes Paiements via sync debt_payment (+ file locale sur formulaire dette) ; création dette surtout via vente crédit / serveur Relances email ; création dette « manuelle » offline si absente de l’API
P1 Caisse Sessions, mouvements (cache) Ouverture / fermeture session, mouvements caisse Rapports PDF serveur-only
P2 Liste ventes (consultation) Ventes récentes en cache — (lecture) Export compta

Règle v1 : toute page non listée = en ligne requise ou message explicite « Indisponible hors connexion ».


2) Données / actions (rappel métier)

  • Pull incrémental : /api/sync/pull?since=… (inclut notamment debts et debt_payments pour l’historique des paiements en local).
  • Push : file locale (sync_queue) → endpoint sync existant ; idempotence par UUID (déjà utilisé côté ventes). Conflits v1 : stratégie « dernier write côté serveur après sync » ; les conflits métier complexes = phase v2 (verrou, notification).

3) Service Worker & PWA

  • Fichier : public/sw.js (cache /build/*, fallback /offline.html).
  • Déploiement : incrémenter CACHE_NAME lors des releases majeures pour forcer le renouvellement du cache (voir commentaire en tête du fichier).

v1 : pas de changement de stratégie globale obligatoire ; vérifier après chaque npm run build que les assets sont bien repris une fois en ligne pour peupler le cache.


4) Une seule brique de sync (serveur)

  • Point d’entrée principal : App\Http\Controllers\Api\SyncController (+ pull / ops). v1 : ne pas créer de second protocole ; toute nouvelle entité hors-ligne doit passer par la même convention (pull chunk + op typée + UUID).

5) Commercialisation / activation

Deux leviers combinables :

  1. Feature boutique offline_mode (paramètres fonctionnalités), comme aujourd’hui.
  2. Plans d’abonnement : via config/offline.php + OFFLINE_MODE_PLANS (valeurs de shops.subscription_plan, ex. premium,enterprise). Les boutiques sur ces plans obtiennent le mode hors-ligne sauf désactivation explicite (offline_mode avec is_enabled = false).

Application : logique centralisée dans App\Support\OfflineModeAccess ; HandleInertiaRequests recalcule offline_mode dans enabledFeatures ; /api/sync/pull et push passent par le middleware offline.mode (refus 403 si pas de droit effectif). La page /offline/sync-status reste consultable pour le message d’upgrade ; les props partagées incluent offlineSubscription (plan actuel, plans éligibles, flag désactivé).

window.__offline côté client suit toujours enabledFeatures.


« Système complet » hors ligne : périmètre réel

Le v1 ne vise pas une copie locale de toute l’application (SFN, exports PDF serveur, achats, RH, analytique avancée, etc.). L’objectif est un noyau terrain utilisable sans réseau : POS, catalogue / stock, clients & dettes en consultation / actions déjà prévues par l’API, caisse, liste des ventes récentes, avec une seule brique sync et une liste d’URLs explicite pour l’UI.

Pour élargir le hors-ligne (nouvelles pages, push d’entités absentes du SyncController, règles métier offline), traiter chaque cas en v2+ : nouvelle op typée, pull si besoin, handler client + tests — sans second protocole parallèle.


Périmètre v2 (cible — cette application web / PWA)

Le v2 concerne ShopManager Pro tel que dans ce dépôt (Laravel + Inertia + pages legacy Blade, PWA avec service worker) — pas un autre logiciel, sauf produit distinct explicitement nommé.

À inclure en priorité v2 (votre niveau « terrain » étendu) :

  • Achats : saisie / consultation des achats hors connexion, impact stock aligné avec le catalogue déjà sync.
  • Fournisseurs : carnet fournisseurs disponible localement ; liaison aux achats.

Peuvent rester « connexion requise » au-delà de v2 (jusqu’à nouvelle décision) : SFN, RH complet, analytique avancée, exports PDF serveur lourds, etc.

Implémentation attendue : même protocole (SyncController pull/push + IndexedDB + offlineV1Routes.js + tests), avec nouvelles entités (ex. suppliers, purchases, lignes d’achat) et ordre de push cohérent (ex. fournisseur avant achat si création chaînée).

État (sync v2 achats / fournisseurs) : le pull inclut suppliers, purchases, purchase_items ; le push accepte suppliers et purchase (création + complétion) ; l’UI legacy Blade exécute les formulaires avec data-inertia="false" et intercepte côté Dexie (purchasesLegacy.js). Les routes /purchases et /suppliers sont dans offlineV1Routes.js. Tests : SyncControllerPurchasesSuppliersTest, pull incluant achats dans SyncControllerPullTest.

Finition v2 (checklist avant de « passer » officiellement en v3 terrain)

Point Détail
Recette terrain Parcours création fournisseur + achat + complétion sans réseau, puis sync au retour ligne
PWA Incrémenter CACHE_NAME / RUNTIME_CACHE dans public/sw.js après livraisons qui touchent les assets (npm run build)
Pas de régression Catalogue / POS / caisse inchangés côté protocole sync unique

Une fois ces points validés en conditions réelles, le périmètre fonctionnel v2 est considéré clos côté produit ; les évolutions suivantes relèvent du v3 (ci-dessous).


Périmètre v3 (cible — après v2 achats / fournisseurs)

Objectif : étendre le noyau terrain sans viser une copie du SaaS complet. Le v3 reste sur la même brique SyncController (pull / push) + IndexedDB + offlineV1Routes.js.

Inclus en priorité v3 (proposition) :

  1. Ventes & historique hors ligne : consultation liste / détail des ventes avec données déjà tirées par le pull (sales, sale_items), recherche / filtres côté client, éventuellement ouverture ticket / reçu depuis cache quand l’URL est couverte (sans promettre tout le module « Rapports »).
  2. Durcissement sync : surface utilisateur pour file d’attente (erreurs, réessai), amorce de gestion de conflits ou messages explicites (la stratégie « dernier write serveur » reste la référence ; affinage = itératif).
  3. POS hors ligne (compléments) : lookup code-barres / cache local (déjà amorcé) — maintenir alignement avec le catalogue sync.

Hors v3 sauf décision produit : SFN / facturation fiscale obligatoire offline, RH complet, analytique avancée, exports PDF lourds serveur-only, import masse catalogue.

Livrables techniques récurrents : tests Feature sur les nouveaux chemins sync si nouvelles ops ; mise à jour offlineV1Routes.js et bannière AppLayout pour toute nouvelle URL « capable hors ligne » ; bump Service Worker à chaque release front pertinente.

Plan détaillé v3 : voir docs/OFFLINE_V3_PERIMETER.md (phases A–E, extensions dettes / fournisseurs, section Clôture v3).

État : périmètre v3 clos côté livrables documentés ; les jalons v4 / v5 (qualité, recette structurée, SW / PWA) sont décrits dans docs/OFFLINE_V4_V5_PERIMETER.md et pourront être planifiés ensuite.

Index de toute la doc hors ligne : docs/OFFLINE_MASTER_INDEX.md.


Prochaines étapes de développement (backlog v1)

  1. Routes v1 (référence unique) : resources/js/offline/offlineV1Routes.js — aligné avec la bannière, catalogueLegacy.js, cashMovementsPage.js, cashLegacy.js (préfixes caisse /cash/sessions/*).
  2. Messages UI : bannière AppLayout.vue (hors URLs capables v1).
  3. Tests SyncController : catalogue + pull + caisse/POS + SyncControllerDebtPaymentTest (debt_payment).
  4. Page « État sync » : /offline/sync-status, lien Administration + Ventes & Caisse.
  5. Service Worker : incrémenter CACHE_NAME / RUNTIME_CACHE dans public/sw.js lors des releases qui touchent les assets — voir version actuelle dans public/sw.js et docs/OFFLINE_V4_V5_PERIMETER.md (périmètre v5).