geo/app/ANDROID-GUIDE.md

# 📱 Guide de Développement Android pour GeoSector

## 🚀 Configuration initiale

### Prérequis sur Debian/Ubuntu
```bash
# Installer les outils Android de base
sudo apt update
sudo apt install adb fastboot android-tools-adb android-tools-fastboot

# Pour le support MTP (transfert de fichiers)
sudo apt install mtp-tools jmtpfs gvfs-backends

# Vérifier l'installation
adb --version
```

### Configuration du téléphone Android
1. **Activer le mode développeur** :
   - Aller dans `Paramètres > À propos du téléphone`
   - Taper 7 fois sur `Numéro de build`
   
2. **Activer le débogage USB** :
   - Aller dans `Paramètres > Options pour développeurs`
   - Activer `Débogage USB`
   - Activer `Installation via USB` (si disponible)
   
3. **Connexion USB** :
   - Brancher le téléphone
   - Autoriser le débogage sur le téléphone (popup)
   - Choisir "Toujours autoriser depuis cet ordinateur"

## 🔍 Commandes ADB essentielles

### Vérification de la connexion
```bash
# Lister les devices connectés
adb devices

# Voir les infos détaillées du device
adb shell getprop | grep -E "model|version|manufacturer"

# Vérifier si le device est en USB
lsusb | grep -i samsung
```

### Installation et gestion des APK
```bash
# Installer un APK
adb install app-release.apk

# Installer en écrasant la version existante
adb install -r app-release.apk

# Installer un APK debug (avec permission de debug)
adb install -t app-debug.apk

# Désinstaller une application
adb uninstall fr.geosector.app3025

# Lister les packages installés
adb shell pm list packages | grep geosector

# Voir le chemin d'installation d'une app
adb shell pm path fr.geosector.app3025
```

## 📊 Logs et débogage en temps réel

### Voir TOUS les logs du téléphone
```bash
# Logs en temps réel (CTRL+C pour arrêter)
adb logcat

# Logs avec filtre sur votre app uniquement
adb logcat | grep -i geosector

# Logs Flutter uniquement (très utile !)
adb logcat | grep -E "flutter|dart"
```

### Logs Flutter spécifiques (RECOMMANDÉ)
```bash
# Méthode 1: Via Flutter directement (le plus pratique)
flutter logs

# Méthode 2: Filtrer par tag Flutter
adb logcat -s flutter

# Méthode 3: Logs avec niveau de verbosité
adb logcat "*:E" # Erreurs uniquement
adb logcat "*:W" # Warnings et erreurs
adb logcat "*:I" # Info, warnings et erreurs
```

### Logs avec timestamps et couleurs
```bash
# Avec timestamp
adb logcat -v time | grep -i geosector

# Format détaillé avec PID
adb logcat -v threadtime | grep -i geosector

# Sauvegarder les logs dans un fichier
adb logcat -d > logs_android.txt
```

### Nettoyer les logs
```bash
# Effacer le buffer de logs
adb logcat -c

# Puis relancer pour voir uniquement les nouveaux logs
adb logcat | grep -i geosector
```

## 🐛 Débogage avancé

### Lancer l'application depuis ADB
```bash
# Démarrer l'application
adb shell monkey -p fr.geosector.app3025 -c android.intent.category.LAUNCHER 1

# Ou avec am (Activity Manager)
adb shell am start -n fr.geosector.app3025/.MainActivity

# Forcer l'arrêt de l'application
adb shell am force-stop fr.geosector.app3025
```

### Capturer des screenshots
```bash
# Prendre une capture d'écran
adb shell screencap /sdcard/screenshot.png
adb pull /sdcard/screenshot.png ./screenshot.png

# Enregistrer une vidéo (appuyer CTRL+C pour arrêter)
adb shell screenrecord /sdcard/demo.mp4
adb pull /sdcard/demo.mp4 ./demo.mp4
```

### Informations système
```bash
# Voir l'utilisation mémoire
adb shell dumpsys meminfo fr.geosector.app3025

# Voir les permissions de l'app
adb shell dumpsys package fr.geosector.app3025 | grep permission

# Version d'Android
adb shell getprop ro.build.version.release

# Taille de l'écran
adb shell wm size

# Densité de l'écran
adb shell wm density
```

## 🔥 Hot Reload avec Flutter

### Développement en temps réel
```bash
# Lancer l'app en mode debug avec hot reload
flutter run

# Une fois lancé, utiliser ces commandes :
# r - Hot reload (rechargement rapide)
# R - Hot restart (redémarrage complet)
# h - Afficher l'aide
# q - Quitter
# p - Afficher/masquer la grille de construction
# o - Basculer iOS/Android
```

### Lancer sur un device spécifique
```bash
# Lister les devices disponibles
flutter devices

# Lancer sur un device spécifique
flutter run -d R3CY409BQBZ  # Remplacer par votre device ID

# Lancer en mode release pour tester les performances
flutter run --release
```

## 🏗️ Build et compilation

### Générer les APK
```bash
# APK debug (non signé, pour tests)
flutter build apk --debug

# APK release (signé, optimisé)
flutter build apk --release

# APK séparés par architecture (plus petits)
flutter build apk --split-per-abi

# App Bundle pour Google Play Store
flutter build appbundle --release
```

### Analyser la taille de l'APK
```bash
# Voir la taille détaillée de l'APK
flutter build apk --analyze-size

# Utiliser l'outil APK Analyzer d'Android
java -jar ~/Android/Sdk/tools/bin/apkanalyzer.jar apk summary app-release.apk
```

## 🔧 Résolution de problèmes courants

### Device non détecté
```bash
# Redémarrer le serveur ADB
adb kill-server
adb start-server
adb devices

# Vérifier les règles udev (Linux)
ls -la /etc/udev/rules.d/ | grep android

# Ajouter les permissions utilisateur
sudo usermod -aG plugdev $USER
# Puis se déconnecter/reconnecter
```

### Permissions Android
```bash
# Accorder une permission manuellement
adb shell pm grant fr.geosector.app3025 android.permission.ACCESS_FINE_LOCATION

# Révoquer une permission
adb shell pm revoke fr.geosector.app3025 android.permission.ACCESS_FINE_LOCATION

# Lister toutes les permissions
adb shell pm list permissions -g
```

### Problème de signature
```bash
# Vérifier la signature de l'APK
jarsigner -verify -verbose -certs app-release.apk

# Voir le certificat
keytool -printcert -jarfile app-release.apk
```

## 📦 Transfert de fichiers

### Via ADB (recommandé pour dev)
```bash
# Envoyer un fichier vers le téléphone
adb push fichier.txt /sdcard/Download/

# Récupérer un fichier du téléphone
adb pull /sdcard/Download/fichier.txt ./

# Lister les fichiers
adb shell ls -la /sdcard/Download/
```

### Via MTP (pour Thunar)
```bash
# Monter le téléphone
jmtpfs ~/phone

# Démonter
fusermount -u ~/phone

# Ou redémarrer Thunar
thunar -q && thunar &
```

## 🎯 Commandes utiles pour GeoSector

### Logs spécifiques à l'application
```bash
# Voir les erreurs de l'API
adb logcat | grep -E "ApiService|ApiException"

# Voir les opérations Hive (base de données locale)
adb logcat | grep -i hive

# Voir les erreurs de géolocalisation
adb logcat | grep -E "geolocator|location"

# Tout voir pour GeoSector
adb logcat | grep -E "geosector|flutter" --color=always
```

### Script de déploiement rapide
Créer un fichier `deploy-android.sh` :
```bash
#!/bin/bash
echo "🚀 Déploiement sur Android..."

# Nettoyer et compiler
flutter clean
flutter pub get
flutter build apk --release

# Installer sur le device
adb install -r build/app/outputs/flutter-apk/app-release.apk

# Lancer l'application
adb shell am start -n fr.geosector.app3025/.MainActivity

# Afficher les logs
echo "📊 Logs en temps réel (CTRL+C pour arrêter)..."
adb logcat | grep -E "geosector|flutter" --color=always
```

Rendre exécutable : `chmod +x deploy-android.sh`

## 🏁 Workflow de développement recommandé

1. **Brancher le téléphone** et vérifier : `adb devices`
2. **Lancer en mode debug** : `flutter run`
3. **Modifier le code** et appuyer sur `r` pour hot reload
4. **Voir les logs** dans un autre terminal : `flutter logs`
5. **Tester la release** : `flutter run --release`
6. **Compiler l'APK final** : `flutter build apk --release`
7. **Installer** : `adb install -r app-release.apk`

## 💡 Tips & Tricks

- **Performance** : Toujours tester en mode `--release` pour juger les vraies performances
- **Logs** : Garder un terminal avec `flutter logs` ouvert en permanence pendant le dev
- **Hot Reload** : Fonctionne uniquement en mode debug, pas en release
- **Wi-Fi Debug** : Possible avec `adb connect <IP>:5555` après configuration
- **Multi-devices** : Flutter peut déployer sur plusieurs devices simultanément

---

*Guide créé pour le projet GeoSector - Mise à jour : Août 2025*