EM2_ERP/em2rp/SYSTEME_MISE_A_JOUR.md

Système de Gestion des Mises à Jour - EM2RP

📋 Vue d'ensemble

Ce système permet de gérer automatiquement les mises à jour de l'application web Flutter, en notifiant les utilisateurs et en forçant le rechargement du cache si nécessaire.

---

🔧 Architecture

Fichiers impliqués

Configuration

• lib/config/app_version.dart : Fichier source de vérité pour la version
• web/version.json : Fichier déployé avec l'app pour vérification côté serveur

Services

• lib/services/update_service.dart : Service de vérification des mises à jour
• lib/views/widgets/common/update_dialog.dart : Widget d'affichage du dialog de mise à jour

Scripts

• scripts/increment_version.js : Incrémente automatiquement la version
• scripts/update_version_json.js : Génère version.json depuis app_version.dart
• deploy.bat : Script de déploiement complet

Documentation

• CHANGELOG.md : Notes de version (utilisées dans le dialog)

---

🚀 Workflow de déploiement

1. Développement normal

Travaillez normalement sur votre code en mode développement.

2. Déploiement d'une nouvelle version

deploy.bat

Ce script exécute automatiquement :

1. ✅ Bascule en mode PRODUCTION
2. ✅ Incrémente la version (0.3.8 → 0.3.9)
3. ✅ Incrémente le buildNumber (1 → 2)
4. ✅ Génère version.json depuis app_version.dart
5. ✅ Build Flutter Web
6. ✅ Déploie sur Firebase Hosting
7. ✅ Retour en mode DÉVELOPPEMENT

3. Mise à jour côté utilisateur

Au prochain chargement de l'app (ou après 2 secondes) :

• L'app vérifie https://em2rp.web.app/version.json
• Compare avec la version locale dans app_version.dart
• Si buildNumber serveur > buildNumber local → Affiche le dialog

---

📝 Format de version

app_version.dart

class AppVersion {
  static const String version = '0.3.8';    // Version sémantique
  static const int buildNumber = 1;         // Numéro de build (incrémenté automatiquement)
  
  static String get fullVersion => 'v$version';
  static String get fullVersionWithBuild => 'v$version+$buildNumber';
}

version.json (déployé)

{
  "version": "0.3.8",
  "buildNumber": 1,
  "updateUrl": "https://em2rp.web.app",
  "forceUpdate": false,
  "releaseNotes": "• Scanner QR Code\n• Génération QR conteneurs\n• Performance améliorée"
}

---

🔄 Comparaison des versions

Le système compare uniquement le buildNumber :

• buildNumber serveur > buildNumber local → Mise à jour disponible
• Ignore les versions identiques même si la version sémantique change

Exemple :

• Local : 0.3.8+1
• Serveur : 0.3.9+2
• Résultat : Mise à jour proposée (2 > 1) ✅

---

🎨 Expérience utilisateur

Mise à jour normale (forceUpdate: false)

┌────────────────────────────────────┐
│ 🔄 Mise à jour disponible          │
├────────────────────────────────────┤
│ Version actuelle : 0.3.8 (1)       │
│ Nouvelle version : 0.3.9 (2)       │
│                                     │
│ Nouveautés :                        │
│ • Scanner QR Code                   │
│ • Performance améliorée             │
│                                     │
│ [Plus tard]  [Mettre à jour] 🔄    │
└────────────────────────────────────┘

Mise à jour forcée (forceUpdate: true)

┌────────────────────────────────────┐
│ ⚠️  Mise à jour requise             │
├────────────────────────────────────┤
│ Version actuelle : 0.3.8 (1)       │
│ Nouvelle version : 0.3.9 (2)       │
│                                     │
│ ⚠️  Cette mise à jour est           │
│    obligatoire pour continuer      │
│                                     │
│           [Mettre à jour] 🔄       │
└────────────────────────────────────┘

---

🛠️ Utilisation avancée

Forcer une mise à jour critique

Si vous déployez un correctif critique :

1. Modifiez web/version.json après le déploiement :

{
  "version": "0.3.9",
  "buildNumber": 2,
  "forceUpdate": true,  // ← Changer à true
  "releaseNotes": "🔴 Correctif de sécurité important"
}

2. Les utilisateurs ne pourront plus fermer le dialog jusqu'à la mise à jour

Personnaliser les notes de version

Éditez CHANGELOG.md avant le déploiement :

## [0.3.9] - 2026-01-16

### Ajouté
- Scanner QR Code pour équipements
- Génération QR pour conteneurs

### Amélioré
- Performance du dialog de sélection
- Gestion du cache

### Corrigé
- Bug de cache des équipements

Les 5 premières lignes de la section seront utilisées dans le dialog.

---

🧪 Tests

Test 1 : Vérification de version locale

// Dans n'importe quel fichier
import 'package:em2rp/config/app_version.dart';

print('Version: ${AppVersion.version}');
print('Build: ${AppVersion.buildNumber}');
print('Full: ${AppVersion.fullVersionWithBuild}');

Test 2 : Forcer l'affichage du dialog

Modifiez temporairement web/version.json :

{
  "buildNumber": 999  // Très grand nombre
}

Rechargez l'app → Le dialog s'affiche immédiatement

Test 3 : Tester le rechargement

1. Cliquez sur "Mettre à jour"
2. Vérifiez que la page se recharge
3. Vérifiez que le cache est vidé (nouvelles ressources chargées)

---

📊 Logs de debug

En mode debug, des logs sont affichés dans la console :

[UpdateService] Current version: 0.3.8+1
[UpdateService] Server version: 0.3.9+2

Si pas de mise à jour disponible, rien ne s'affiche.

---

🔐 Sécurité

Headers HTTP pour forcer le non-cache

Le fichier web/index.html contient :

<meta http-equiv="Cache-Control" content="no-cache, no-store, must-revalidate">
<meta http-equiv="Pragma" content="no-cache">
<meta http-equiv="Expires" content="0">

Cache-busting sur version.json

Chaque requête ajoute un timestamp :

final timestamp = DateTime.now().millisecondsSinceEpoch;
Uri.parse('$versionUrl?t=$timestamp')

Garantit que la version la plus récente est toujours récupérée.

---

🚨 Résolution de problèmes

Problème : Le dialog ne s'affiche pas

Causes possibles :

1. Le buildNumber serveur n'est pas supérieur au local
2. Erreur réseau (timeout 10s)
3. Le fichier version.json n'existe pas sur le serveur

Solution :

# Vérifier la version déployée
curl https://em2rp.web.app/version.json

# Forcer un nouveau déploiement
deploy.bat

Problème : Le cache ne se vide pas

Causes possibles :

1. Service Worker actif (ancienne version)
2. Cache navigateur très persistant

Solution :

// Dans les DevTools du navigateur
navigator.serviceWorker.getRegistrations().then(registrations => {
  registrations.forEach(r => r.unregister());
});

// Puis CTRL+SHIFT+R (rechargement forcé)

Problème : Le script increment_version.js échoue

Solution :

# Vérifier la syntaxe du fichier app_version.dart
# Doit contenir exactement :
static const String version = '0.3.8';
static const int buildNumber = 1;

---

📈 Évolution future

Fonctionnalités possibles

• Afficher un changelog complet dans le dialog
• Permettre de sauter une version (skip this version)
• Notifications push pour les mises à jour critiques
• Analytics sur le taux d'adoption des mises à jour
• Support des mises à jour en arrière-plan

Améliorations techniques

• Utiliser un CDN pour version.json
• Implémenter un rollback automatique si erreur
• Ajouter une vérification de santé post-déploiement

---

🎯 Commandes rapides

# Déployer une nouvelle version
deploy.bat

# Incrémenter manuellement la version
node scripts\increment_version.js

# Générer version.json manuellement
node scripts\update_version_json.js

# Vérifier la version actuelle
type lib\config\app_version.dart

# Vérifier la version déployée
curl https://em2rp.web.app/version.json

---

✅ Checklist de déploiement

Avant chaque déploiement :

• Tester l'application en local
• Mettre à jour CHANGELOG.md avec les nouveautés
• Vérifier que tous les tests passent
• Exécuter deploy.bat
• Vérifier le déploiement sur https://em2rp.web.app
• Tester la mise à jour sur un navigateur propre
• Informer l'équipe de la nouvelle version

---

📞 Support

En cas de problème avec le système de mise à jour, vérifier :

1. Les logs dans la console du navigateur
2. Le fichier version.json déployé
3. Le fichier app_version.dart local
4. La connexion réseau de l'utilisateur

Le système est conçu pour échouer silencieusement : Si une erreur se produit, l'utilisateur peut continuer à utiliser l'app normalement sans être bloqué.