Comment migrer depuis une installation héritée

Ce guide importe vos données existantes depuis une ancienne installation HandyCafe V3 ou V4 vers un serveur HandyCafe moderne. La migration n'est pas destructive pour la source : les fichiers d'origine ne sont ni modifiés ni supprimés.

La migration de la base de données s'exécute uniquement sous Windows. La prise en charge runtime des clients hérités via le protocole d'origine fonctionne sur toutes les plateformes (voir Paramètres des clients hérités).

Ce dont vous aurez besoin

• Une machine Windows avec à la fois l'installation héritée et le serveur HandyCafe moderne sur le même système, ou bien un accès au fichier de base de données hérité.
• Un accès administrateur au HandyCafe Server.
• Le serveur hérité arrêté. La base de données source ne doit pas être écrite activement pendant la migration.
• Un espace disque libre au moins égal à la taille de la base de données héritée (pour la nouvelle copie de la base HandyCafe).
• 10 à 30 minutes de temps sans interruption. Les migrations sur des jeux de données volumineux peuvent prendre plusieurs minutes. Ne fermez pas HandyCafe pendant l'exécution.

Etape 1 : arrêter le serveur hérité

Ouvrez l'application serveur HandyCafe héritée. Arrêtez toutes les sessions puis quittez l'application. Si le serveur hérité s'exécute comme service Windows, arrêtez le service depuis services.msc.

Résultat attendu : Le processus du serveur hérité n'est plus en cours d'exécution. Le fichier de base de données n'est plus ouvert.

Etape 2 : ouvrir la page Paramètres des clients hérités

1. Lancez HandyCafe.
2. Ouvrez Settings dans la barre latérale.
3. Cliquez sur Legacy Clients.
4. Faites défiler jusqu'à la section Database Migration.

Résultat attendu : Si le système détecte une installation héritée, la page affiche le chemin d'installation, le chemin de la base de données, la version du serveur et le nombre de fichiers INI. Si rien n'est détecté, la page affiche "No legacy installation detected." Dans ce cas, vérifiez que les fichiers hérités existent dans un emplacement standard comme Program Files\HandyCafe ou C:\HandyCafe.

Etape 3 : vérifier l'installation détectée

Assurez-vous que les valeurs détectées correspondent à votre installation héritée connue :

Si un champ est incorrect, fermez HandyCafe, corrigez l'installation puis rouvrez l'application.

Etape 4 : vérifier le champ d'encodage

Avant de lancer la migration, confirmez que le champ Encoding dans la section Runtime Protocol est correctement réglé pour vos données source. Ce champ se trouve sur la même page de paramètres, un peu plus haut.

Si vous modifiez l'encodage, cliquez sur Save avant de continuer.

Résultat attendu : Les chaînes source se décodent proprement pendant la migration, ce qui évite un résultat completed_with_warnings.

Etape 5 : lancer la migration

1. Cliquez sur Start Migration.
2. Une fenêtre de progression s'ouvre. Elle affiche la phase actuelle et le nombre de lignes traitées jusqu'à présent.
3. Ne fermez pas HandyCafe et ne mettez pas l'ordinateur en veille.
4. Attendez la fin. Les petits ensembles de données se terminent en moins d'une minute. Les plus gros peuvent prendre 5 à 10 minutes.

Résultat attendu : La fenêtre de progression se ferme et l'état passe à completed ou completed_with_warnings. Une notification confirme l'exécution.

Etape 6 : vérifier les comptes migrés

Une fois terminé, la page affiche les comptes des enregistrements migrés :

Cliquez sur le volet Details pour voir le détail complet. Vérifiez que les comptes paraissent cohérents avec vos attentes.

Résultat attendu : Les quatre grandes catégories (membres, produits, commandes, transactions) affichent des valeurs non nulles si votre source contenait des données dans ces tables.

Etape 7 : traiter les avertissements le cas échéant

Si l'état est completed_with_warnings, dépliez la liste des avertissements et examinez les enregistrements ignorés.

Avertissements courants et corrections :

Résultat attendu : Vous acceptez les avertissements comme pertes connues et acceptables, ou vous corrigez le problème sous-jacent puis relancez la migration.

Etape 8 : contrôler manuellement les données importées

Avant de mettre le serveur hérité hors service, vérifiez manuellement un échantillon de chaque type d'enregistrement.

1. Ouvrez Members dans la barre latérale. Recherchez un membre que vous connaissez du système hérité. Vérifiez le nom, le solde et les coordonnées.
2. Ouvrez Settings > Pricing. Vérifiez que les tarifs horaires correspondent au planning hérité.
3. Ouvrez Products. Vérifiez les noms et les prix des produits.
4. Ouvrez Cash Report pour un jour historique récent. Vérifiez que les totaux correspondent à ce que vous attendez du système hérité.

Résultat attendu : Les échantillons aléatoires correspondent à la source héritée. Si un enregistrement particulier est faux, notez le problème. Les petites différences de format sont normales. Les écarts de valeur importants suggèrent un problème d'encodage ou d'intégrité des données qui mérite d'être examiné avant la mise en production.

Etape 9 : activer la prise en charge runtime des clients hérités (facultatif)

Si vous voulez que vos machines clientes V3 ou V4 existantes continuent de se connecter pendant la transition, activez maintenant le protocole runtime.

1. Faites défiler jusqu'en haut de la page Paramètres des clients hérités.
2. Activez Enable Legacy Client Support.
3. Vérifiez que les ports d'écoute (UDP 710, TCP 712, transfert de fichiers 717) n'entrent en conflit avec rien d'autre sur votre réseau.
4. Cliquez sur Save.

Résultat attendu : Les clients hérités sur le LAN apparaissent dans le panneau d'administration en 5 à 10 secondes. Consultez Clients hérités pour savoir comment les gérer depuis le panneau.

Comment annuler une migration

Si la migration produit des résultats inattendus, vous pouvez la revenir entièrement en arrière. La base héritée d'origine n'est pas touchée.

1. Ouvrez Settings > Legacy Clients.
2. Faites défiler jusqu'à la section Database Migration.
3. Cliquez sur Undo Migration.
4. Confirmez dans la boîte de dialogue.

Chaque ligne migrée est supprimée de HandyCafe. L'état revient à never. Vous pouvez ensuite corriger le problème sous-jacent (encodage, nettoyage des données source, etc.) et relancer Start Migration.

Comment relancer une migration

Relancer remplace les données migrées par des données fraîches provenant de la source.

1. Ouvrez Settings > Legacy Clients.
2. Cliquez sur Re-run Migration (le bouton est renommé après la première exécution terminée).
3. Le flux est identique à celui de l'exécution initiale.

Re-run peut être utilisé autant de fois que nécessaire. Il ne duplique pas les données car il remplace le résultat de migration existant.

Erreurs courantes à éviter

• Lancer la migration pendant que le serveur hérité est actif. La base source peut être verrouillée ou contenir des écritures partielles. Arrêtez toujours le serveur hérité en premier.
• Ignorer le champ Encoding. Lancer avec le mauvais encodage corrompt les noms des membres et les messages de journal. Corriger cela après coup nécessite Undo puis Re-run.
• Fermer HandyCafe pendant la migration. L'exécution est interrompue et des données partielles sont écrites. La récupération nécessite Undo. Laissez toujours la fenêtre de progression aller jusqu'au bout.
• Sauter l'étape de contrôle manuel. Se fier aux seuls comptes d'enregistrements sans vérifier des données d'échantillon peut masquer des problèmes subtils comme des décalages de locale ou des erreurs d'arrondi.
• Supprimer l'installation héritée trop tôt. Conservez les fichiers source pendant au moins un cycle de paiement complet après la migration. Si une divergence apparaît sur un rapport mensuel, vous pourrez vous référer aux enregistrements d'origine.
• Migrer sans sauvegarde. Copiez le dossier d'installation hérité avant la première migration. Même si la migration ne modifie pas la source, un problème de disque ou un accident peut toujours arriver. Une sauvegarde est une assurance peu coûteuse.