Synchronisation offline

SmartMaker ne propose pas un mécanisme de synchronisation, mais trois, qui ne servent pas au même usage. Choisir le mauvais est la principale cause de travail jeté dans un projet offline.

Cette page sert d'aiguillage. Chaque dispositif est ensuite détaillé dans sa propre page.

Choisir son dispositif

Les trois se combinent. CapFullPOS, par exemple, tire son catalogue avec useReferenceSync et pousse ses ventes avec useSyncClient.

1. useSyncClient : moteur transactionnel générique

useSyncClient synchronise des objets Dolibarr champ par champ, dans les deux sens, avec détection de conflits. C'est le dispositif à préférer quand vos écrans manipulent directement des objets du modèle Dolibarr.

Architecture

Le hook parle aux endpoints /sync/* exposés par le SyncController de SmartAuth. Rien n'est à écrire côté serveur pour les 26 types d'objets déjà enregistrés.

Mise en route

L'enregistrement du client est obligatoire et n'est pas automatique : sync() ne s'enregistre pas tout seul. Sans client_uuid, aucun push ni pull ne peut aboutir. Appelez register() une fois, typiquement juste après l'identification de l'appareil.

import { useEffect } from 'react';
import { useSyncClient } from '@cap-rel/smartcommon';

const SyncBootstrap = ({ deviceUuid }) => {
    const {
        isInitialized,
        isRegistered,
        register,
        sync,
        isOnline,
        pendingCount
    } = useSyncClient({
        apiUrl: '/api/smartauth',
        getAccessToken: () => localStorage.getItem('access_token'),
        scope: ['thirdparty', 'contact', 'product'],
        autoSync: true,
        syncInterval: 300000
    });

    useEffect(() => {
        if (isInitialized && !isRegistered && deviceUuid) {
            register(deviceUuid);
        }
    }, [isInitialized, isRegistered, deviceUuid, register]);

    return (
        <span>
            {isOnline ? 'En ligne' : 'Hors ligne'} - {pendingCount} en attente
        </span>
    );
};

Le deviceUuid provient du JWT SmartAuth. Voir SmartAuth pour l'identification d'appareil.

Options

Valeurs retournées

upsert avec queueChange à false écrit en local sans rien pousser. C'est la bonne méthode pour mettre en cache une réponse serveur. Avec queueChange à true, la modification rejoint la file de push.

Flux de synchronisation

Push, du local vers le serveur :

1. L'utilisateur modifie des données localement (create / update / remove)
2. Les changements sont stockés dans IndexedDB (pending_changes)
3. sync() ou push() les envoie par lots de 50 maximum
4. Le serveur confirme, ou signale un conflit
5. Les id temporaires locaux sont remplacés par les id serveur

Pull, du serveur vers le local :

1. sync() ou pull() demande les changements depuis lastSyncTime
2. Le serveur renvoie les entités modifiées, page par page
3. Les entités locales sont mises à jour
4. Si une entité a bougé des deux côtés, un conflit est enregistré
5. Le marqueur lastSyncTime n'avance qu'une fois toutes les pages traitées

Ce dernier point est volontaire : une coupure en cours de pull laisse le marqueur intact, donc la passe suivante reprend tout plutôt que de sauter silencieusement des enregistrements.

Gestion des conflits

Un conflit est créé quand une entité a été modifiée localement et sur le serveur depuis la dernière synchronisation. La détection s'appuie sur le tms de l'objet Dolibarr, comparé champ par champ.

Les résolutions sont 'client', 'server', ou un objet de fusion passé en troisième argument.

const conflicts = await sync.getConflicts();

for (const conflict of conflicts) {
    // Garder la version client
    await sync.resolveConflict(conflict.conflict_id, 'client');

    // Garder la version serveur
    await sync.resolveConflict(conflict.conflict_id, 'server');

    // Fusionner champ par champ
    await sync.resolveConflict(conflict.conflict_id, 'client', {
        ...conflict.server_data,
        label: conflict.client_data.label
    });
}

Le composant ConflictResolver fournit l'interface correspondante :

import { useState, useEffect } from 'react';
import { ConflictResolver, useSyncClient } from '@cap-rel/smartcommon';

const ConflictsPage = () => {
    const sync = useSyncClient({ /* ... */ });
    const [conflicts, setConflicts] = useState([]);

    useEffect(() => {
        sync.getConflicts().then(setConflicts);
    }, []);

    if (conflicts.length === 0) return null;

    return (
        <ConflictResolver
            conflicts={conflicts}
            onResolve={async (conflictId, resolution, data) => {
                await sync.resolveConflict(conflictId, resolution, data);
                setConflicts(prev => prev.filter(c => c.conflict_id !== conflictId));
            }}
            onCancel={() => setConflicts([])}
        />
    );
};

Il affiche une comparaison côte à côte, marque les champs en conflit, propose de garder le client, le serveur ou de fusionner champ par champ, et navigue entre les conflits multiples.

Schéma IndexedDB

useSyncClient gère sa propre base, distincte de celle de votre module.

Conséquence pratique : vos écrans lisent les données par getEntity et queryEntities, pas directement dans les stores Dexie du module. Si vous voulez garder la main sur vos propres stores, c'est useReferenceSync qu'il vous faut.

Ce que useSyncClient ne fait pas

• Il ne synchronise pas des actions métier, seulement des états d'objets. Une clôture de fiche, un changement de statut soumis à des règles serveur ou un envoi de document ne se modélisent pas comme une mise à jour de champs.
• Il ne gère pas les objets composites (documents avec leurs lignes). C'est prévu, ce n'est pas implémenté.
• Il n'embarque pas les fichiers joints. Voir Synchronisation - catalogue de référence pour les blobs.

2. useReferenceSync : catalogue de référence, pull seul

Quand l'application a besoin de consulter hors connexion un référentiel volumineux, sans jamais le modifier, useSyncClient est surdimensionné et sa base séparée devient une gêne.

useReferenceSync tire les données dans vos propres stores Dexie, avec les images et PDF associés téléchargés en lots ZIP, et vos écrans interrogent directement ces stores.

Voir Synchronisation - catalogue de référence.

3. File d'attente d'actions métier

Certains modules ne synchronisent pas des lignes de table mais des gestes métier : clôturer une intervention, ajouter une pièce consommée, faire remonter une photo annotée et signée. La sémantique, les règles de validation et l'idempotence vivent alors dans les contrôleurs du module, pas dans un moteur générique.

C'est le choix de smartInterventions. Le principe :

• chaque geste est écrit en local comme une ligne de file d'attente, avec un client_uuid généré côté client qui sert de clé d'idempotence ;
• la file est vidée au retour en ligne, en appelant les endpoints métier du module ;
• le serveur reconnaît un rejeu grâce au client_uuid et répond sans dupliquer ;
• une ligne en échec reste visible, avec son message d'erreur, pour un nouvel essai manuel.

Ce n'est pas une solution de repli faute de moteur générique : c'est le seul modèle correct quand l'action à rejouer n'est pas réductible à un UPDATE de champs.

Voir Mode offline pour le pattern complet.

Ce qui est commun aux trois

Détection de connectivité

useOnlineStatus est utilisé par les trois, directement ou indirectement. Il combine l'état du navigateur et un health check serveur optionnel, avec un délai de stabilité avant de déclarer le retour en ligne.

const { isOnline, isServerReachable, checkNow } = useOnlineStatus({
    healthCheckUrl: '/api/smartauth/sync/status',
    healthCheckInterval: 60000,
    stabilityDelay: 2000
});

Sans healthCheckUrl, seul navigator.onLine est consulté, ce qui ne détecte pas un portail captif ni un serveur tombé.

Enregistrement du client

useSyncClient et useReferenceSync appellent tous deux POST /sync/register et manipulent un client_uuid. La différence tient à qui le fabrique : useSyncClient reçoit du serveur le client_uuid issu du deviceUuid que vous lui passez, useReferenceSync en génère un et le persiste lui-même dans son store de métadonnées.

Mise à jour de l'application

Activer une nouvelle version du Service Worker ne détruit pas les files d'attente : elles vivent dans IndexedDB, pas dans le cache du Service Worker. Voir PWA pour usePWAUpdate, UpdatePrompt et la prop pwaUpdate du Provider.

Le rôle des classes Dm

Côté serveur, ce sont les mêmes mappers Dm<Entity> qui servent la façade REST et la synchronisation. En particulier, l'allowlist d'écriture d'un objet synchronisé est le $writableFields de son mapper : un champ qui n'y figure pas est rejeté silencieusement au push. Voir Mapping Dolibarr - React.

Voir aussi

• Synchronisation - catalogue de référence - useReferenceSync en détail
• Hooks SmartCommon - tous les hooks
• Stockage de données - useDb, useCachedQuery
• PWA - Service Worker et mises à jour
• Mapping Dolibarr - React - les classes Dm