# 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**

```bash
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**

```bash
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**

```bash
# 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**

```bash
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**

```bash
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)

```bash
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**

```bash
# 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**

```bash
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**

```bash
# 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