geo/app/MIGRATION_FLUTTER_3.24.5.md

Migration Flutter 3.24.5 LTS - Résolution problèmes iOS SwiftPM

Date : 11/10/2025 Objectif : Résoudre les erreurs de compilation iOS liées à l'architecture SwiftPM Solution : Downgrade Flutter 3.24.5 LTS + downgrade des packages SwiftPM

---

📊 Tableau récapitulatif des changements

Package	Version avant	Version après	Raison du changement
Flutter SDK	3.35.5+	3.24.5 LTS	Bugs SwiftPM dans 3.35.x
Dart SDK	3.9.2	3.5.4	Inclus avec Flutter 3.24.5
package_info_plus	8.3.1	4.2.0	Avant SwiftPM - 'Flutter/Flutter.h' file not found
network_info_plus	7.0.0	4.1.0	Avant SwiftPM - Erreurs module Swift
sensors_plus	7.0.0	3.1.0	Avant SwiftPM - Erreurs FPPSensorsPlusPlugin.h
image_picker	1.1.2	0.8.9	Avant SwiftPM - Erreurs image_picker_ios
url_launcher	6.3.1	6.1.14	Version stable compatible
go_router	16.0.0	15.1.2	Compatible Flutter 3.24.5
flutter_map	8.2.2	7.0.2	Compatible Flutter 3.24.5
flutter_map_cache	2.0.0	1.5.1	Compatible Flutter 3.24.5
syncfusion_flutter_charts	31.1.22	29.1.38	Compatible Flutter 3.24.5
flutter_stripe	12.0.0	11.5.0	Compatible Dart 3.5.4
nfc_manager	4.1.1	3.5.0	Compatible Flutter 3.24.5
device_info_plus	12.1.0	11.3.0	Compatible Flutter 3.24.5
flutter_lints	6.0.0	5.0.0	Compatible Dart 3.5.4
intl	0.20.2	0.19.0	Piné par Flutter 3.24.5 SDK

---

⚠️ Problèmes résolus

Erreurs de compilation iOS éliminées :

• ❌ 'Flutter/Flutter.h' file not found dans plugins SwiftPM
• ❌ No such module 'Flutter' en Swift
• ❌ Erreurs de linking architecture x86_64
• ❌ Incompatibilités SwiftPM entre Flutter et plugins
• ❌ Problèmes url_launcher_ios, sensors_plus, image_picker_ios

---

✅ Fonctionnalités conservées

Toutes les fonctionnalités critiques restent opérationnelles :

• ✅ Stripe Tap to Pay (mek_stripe_terminal 4.6.0 inchangé)
• ✅ PaymentSheets, Apple Pay, Google Pay
• ✅ Stripe Connect V1
• ✅ SCA/PSD2
• ✅ Géolocalisation GPS (geolocator 14.0.2)
• ✅ NFC (nfc_manager 3.5.0)
• ✅ Flutter Maps (flutter_map 7.0.2)
• ✅ Charts Syncfusion (syncfusion_flutter_charts 29.1.38)
• ✅ Upload d'images (image_picker 0.8.9)
• ✅ Notifications locales
• ✅ Toutes les fonctionnalités métier

---

📉 Fonctionnalités perdues (non critiques)

Fonctionnalités récentes des packages downgradés :

• ⚠️ Options avancées PaymentSheet ajoutées dans flutter_stripe 12.x
• ⚠️ Méthode pickMultipleMedia() de image_picker 1.x (reste pickMultiImage())
• ⚠️ Fonctionnalités NFC avancées de nfc_manager 4.x
• ⚠️ APIs récentes de package_info_plus 8.x
• ⚠️ Nouvelles APIs network_info_plus 7.x

Impact métier : Aucun - Les fonctionnalités perdues ne sont pas utilisées dans l'app.

---

🚀 Procédure de migration

Étape 1 : Downgrade Flutter vers 3.24.5 LTS

cd ~/dev/flutter
git checkout 3.24.5
flutter --version

Vérification attendue :

Flutter 3.24.5 • channel stable
Dart 3.5.4 • DevTools 2.37.3

Étape 2 : Nettoyer complètement le projet

cd /home/pierre/dev/geosector/app

# Nettoyer Flutter
flutter clean

# Supprimer les dépendances existantes
rm pubspec.lock
rm -rf ios/Pods ios/Podfile.lock ios/.symlinks
rm -rf build
rm -rf .dart_tool

# Supprimer les caches Flutter
flutter pub cache repair

Étape 3 : Installer les nouvelles dépendances

# Récupérer les packages Flutter avec le nouveau pubspec.yaml
flutter pub get

Vérification attendue : Aucune erreur de résolution de dépendances.

Étape 4 : Réinstaller les Pods iOS

cd ios

# Mettre à jour le repo CocoaPods
pod repo update

# Installer les pods
pod install

Vérification attendue : ~25-26 pods installés sans erreur.

Étape 5 : Tester la compilation iOS

cd ..

# Tester la compilation sans signature
flutter build ios --release --no-codesign

Résultat attendu : Compilation réussie sans erreur SwiftPM.

Étape 6 : Vérification finale dans Xcode (optionnel)

open ios/Runner.xcworkspace

Actions dans Xcode :

1. Sélectionner Runner target
2. Product > Clean Build Folder (Cmd+Shift+K)
3. Product > Build (Cmd+B)
4. Vérifier qu'il n'y a pas d'erreurs de compilation

---

🔍 Vérifications post-migration

Checklist de validation :

• Flutter version : 3.24.5
• Dart version : 3.5.4
• flutter pub get : ✅ Sans erreurs
• pod install : ✅ ~25-26 pods installés
• flutter build ios --release --no-codesign : ✅ Compilation réussie
• flutter analyze : ✅ Pas d'erreurs bloquantes
• App démarre en simulateur iOS : ✅
• Fonctionnalités critiques testées :
  • Login / Authentification
  • Géolocalisation GPS
  • Cartes Flutter Maps
  • Upload d'images
  • Charts Syncfusion
  • NFC (si device compatible)

---

🔧 Dépannage

Si flutter pub get échoue

# Réparer le cache Pub
flutter pub cache repair

# Supprimer le lock et réessayer
rm pubspec.lock
flutter pub get

Si pod install échoue

cd ios

# Nettoyer complètement CocoaPods
rm -rf Pods Podfile.lock
rm -rf ~/Library/Caches/CocoaPods
pod cache clean --all

# Réinstaller
pod repo update
pod install

Si erreurs de compilation persistent

# Nettoyer Xcode derived data
rm -rf ~/Library/Developer/Xcode/DerivedData

# Nettoyer complètement Flutter
flutter clean
rm -rf build ios/.symlinks

# Réinstaller tout
flutter pub get
cd ios && pod install

Si erreurs "module not found" dans Xcode

1. Ouvrir ios/Runner.xcworkspace dans Xcode
2. Product > Clean Build Folder (Cmd+Shift+K)
3. Fermer Xcode
4. Relancer pod install
5. Rouvrir Xcode et rebuild

---

📌 Points d'attention

NE PAS upgrader Flutter

• ⚠️ Ne pas exécuter flutter upgrade
• ⚠️ Rester sur Flutter 3.24.5 LTS pour stabilité iOS
• ⚠️ Les versions 3.35.x ont des bugs SwiftPM non résolus

Versions verrouillées critiques

• intl: 0.19.0 - Piné par Flutter SDK, ne pas modifier
• flutter_stripe: ^11.5.0 - Version max compatible Dart 3.5.4
• package_info_plus: ^4.2.0 - Ne pas upgrader vers 5.0+ (SwiftPM)
• network_info_plus: ^4.1.0 - Ne pas upgrader vers 5.0+ (SwiftPM)
• sensors_plus: ^3.1.0 - Ne pas upgrader vers 4.0+ (SwiftPM)

Compatibilité future

• Migration vers Flutter 3.28+ LTS envisageable quand SwiftPM sera stable
• Surveillance des changelogs Flutter pour support SwiftPM complet
• Prévoir test de migration tous les 6 mois

---

📚 Références

Problème SwiftPM Flutter iOS

• Flutter Issue #137945 : SwiftPM integration issues
• Flutter Issue #144832 : 'Flutter/Flutter.h' file not found
• Flutter Docs : https://docs.flutter.dev/packages-and-plugins/swift-package-manager

Versions Flutter

• Flutter 3.24.5 Release Notes : https://github.com/flutter/flutter/releases/tag/3.24.5
• Flutter LTS Policy : https://docs.flutter.dev/release/archive

Packages downgradés

• package_info_plus changelog : https://pub.dev/packages/package_info_plus/changelog
• network_info_plus changelog : https://pub.dev/packages/network_info_plus/changelog
• sensors_plus changelog : https://pub.dev/packages/sensors_plus/changelog
• image_picker changelog : https://pub.dev/packages/image_picker/changelog

---

✅ Validation finale

Migration réussie si :

1. ✅ Flutter 3.24.5 installé
2. ✅ Tous les packages résolus sans conflit
3. ✅ Pods iOS installés sans erreur
4. ✅ Compilation iOS réussie sans erreurs SwiftPM
5. ✅ App démarre et fonctionne en simulateur iOS
6. ✅ Fonctionnalités critiques testées et opérationnelles

---

Dernière mise à jour : 11/10/2025 - 15:00 Statut : ✅ pubspec.yaml préparé, prêt pour migration Prochaine étape : Exécuter la procédure de migration