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 notammentdebtsetdebt_paymentspour 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_NAMElors 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 :
- Feature boutique
offline_mode(paramètres fonctionnalités), comme aujourd’hui. - Plans d’abonnement : via
config/offline.php+OFFLINE_MODE_PLANS(valeurs deshops.subscription_plan, ex.premium,enterprise). Les boutiques sur ces plans obtiennent le mode hors-ligne sauf désactivation explicite (offline_modeavecis_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) :
- 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 »). - 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).
- 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)
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/*).Messages UI : bannièreAppLayout.vue(hors URLs capables v1).TestsSyncController: catalogue + pull + caisse/POS +SyncControllerDebtPaymentTest(debt_payment).Page « État sync » :/offline/sync-status, lien Administration + Ventes & Caisse.- Service Worker : incrémenter
CACHE_NAME/RUNTIME_CACHEdanspublic/sw.jslors des releases qui touchent les assets — voir version actuelle danspublic/sw.jsetdocs/OFFLINE_V4_V5_PERIMETER.md(périmètre v5).