(doc) : ajout et modification de docs après arbitrage

2026-01-31 21:09:59 +01:00
parent f99fb3c614
commit 841028d1b2
24 changed files with 3081 additions and 301 deletions
--- a/docs/adr/022-librairies-flutter.md
+++ b/docs/adr/022-librairies-flutter.md
@@ -0,0 +1,207 @@
+# ADR-022 : Librairies Flutter du Mobile
+
+**Statut** : Accepté
+**Date** : 2026-01-31
+
+## Contexte
+
+L'application mobile RoadWave (iOS/Android) nécessite des librairies tierces pour audio HLS, géolocalisation, notifications, state management, etc. Le choix doit privilégier :
+- **Licences permissives** (MIT, Apache-2.0, BSD) sans restrictions commerciales
+- **Maturité** et maintenance active (écosystème Flutter)
+- **Performance native** (pas de bridge JS)
+- **Support CarPlay/Android Auto**
+- **Conformité stores** (App Store, Play Store)
+
+## Décision
+
+Utilisation de **8 librairies open-source** Flutter avec licences permissives.
+
+### Core Stack
+
+| Catégorie | Librairie | Licence | Justification |
+|-----------|-----------|---------|---------------|
+| **State Management** | `flutter_bloc` | MIT | Pattern BLoC, 11K+ stars, reactive streams |
+| **Audio HLS** | `just_audio` | MIT | HLS natif, buffering adaptatif, background playback |
+| **HTTP Client** | `dio` | MIT | Interceptors, retry logic, 12K+ stars |
+| **Stockage sécurisé** | `flutter_secure_storage` | BSD-3 | Keychain iOS, KeyStore Android |
+| **Cache images** | `cached_network_image` | MIT | LRU cache, placeholder support |
+
+### Géolocalisation & Permissions
+
+| Catégorie | Librairie | Licence | Justification |
+|-----------|-----------|---------|---------------|
+| **GPS temps réel** | `geolocator` | MIT | Mode voiture, high accuracy, background modes |
+| **Geofencing** | `geofence_service` | MIT | Détection rayon 200m, mode piéton, économie batterie |
+| **Notifications locales** | `flutter_local_notifications` | BSD-3 | Compteur dynamique, icônes custom, iOS/Android |
+
+### Packages Additionnels (CarPlay/Android Auto)
+
+| Catégorie | Librairie | Licence | Justification |
+|-----------|-----------|---------|---------------|
+| **CarPlay** | `flutter_carplay` | MIT | Intégration CarPlay native (communautaire) |
+| **Android Auto** | `android_auto_flutter` | Apache-2.0 | Support Android Auto (communautaire) |
+| **Permissions** | `permission_handler` | MIT | Gestion unifiée permissions iOS/Android |
+
+## Alternatives considérées
+
+### State Management
+- **flutter_bloc** (choisi) : Pattern BLoC, testable, reactive
+- **riverpod** : Plus moderne, moins mature
+- **provider** : Simple mais limité pour app complexe
+- **getx** : Performance mais opinions controversées
+
+### Audio
+- **just_audio** (choisi) : HLS natif, communauté active
+- **audioplayers** : Moins mature pour streaming
+- **flutter_sound** : Orienté recording, pas streaming
+
+### Géolocalisation
+- **geolocator** (choisi) : Standard Flutter, 1.2K+ stars
+- **location** : Moins maintenu
+- **background_location** : Spécifique background uniquement
+
+## Justification
+
+### Licences
+- **7/8 librairies** : MIT (permissive totale)
+- **1/8** : BSD-3 (permissive, compatible commercial)
+- **Compatibilité totale** : Aucun conflit de licence, aucune restriction commerciale
+
+### Maturité
+- **flutter_bloc** : 11.6K stars, adoption large (state management standard)
+- **just_audio** : 900+ stars, utilisé production (podcasts apps)
+- **geolocator** : 1.2K stars, maintenu BaseFlow (entreprise Flutter)
+- **dio** : 12K+ stars, client HTTP le plus utilisé Flutter
+
+### Performance
+- **Compilation native** : Dart → ARM64 (pas de bridge JS comme React Native)
+- **just_audio** : Utilise AVPlayer (iOS) et ExoPlayer (Android) natifs
+- **geolocator** : Accès direct CoreLocation (iOS) et FusedLocation (Android)
+- **geofence_service** : Geofencing natif, minimise consommation batterie
+
+### Conformité Stores
+- **Permissions progressives** : `permission_handler` + stratégie ADR-014
+- **Background modes** : `geolocator` + `geofence_service` approuvés stores
+- **Notifications** : `flutter_local_notifications` conforme guidelines iOS/Android
+
+## Architecture
+
+```mermaid
+graph TB
+    subgraph UI["Presentation Layer"]
+        Widgets["Flutter Widgets"]
+        Bloc["flutter_bloc<br/>(State Management)"]
+    end
+
+    subgraph Data["Data Layer"]
+        API["dio<br/>(HTTP Client)"]
+        Storage["flutter_secure_storage<br/>(JWT Tokens)"]
+        Cache["cached_network_image<br/>(Image Cache)"]
+    end
+
+    subgraph Services["Services Layer"]
+        Audio["just_audio<br/>(HLS Streaming)"]
+        GPS["geolocator<br/>(GPS Mode Voiture)"]
+        Geofence["geofence_service<br/>(Mode Piéton)"]
+        Notif["flutter_local_notifications<br/>(Alerts Locales)"]
+        Perms["permission_handler<br/>(Permissions iOS/Android)"]
+    end
+
+    subgraph Platform["Platform Integration"]
+        CarPlay["flutter_carplay<br/>(iOS)"]
+        AndroidAuto["android_auto_flutter<br/>(Android)"]
+    end
+
+    Widgets --> Bloc
+    Bloc --> API
+    Bloc --> Audio
+    Bloc --> GPS
+    Bloc --> Geofence
+
+    API --> Storage
+    Widgets --> Cache
+
+    GPS --> Perms
+    Geofence --> Perms
+    Geofence --> Notif
+
+    Audio --> CarPlay
+    Audio --> AndroidAuto
+
+    classDef uiStyle fill:#e3f2fd,stroke:#1565c0,stroke-width:2px
+    classDef dataStyle fill:#f3e5f5,stroke:#6a1b9a,stroke-width:2px
+    classDef serviceStyle fill:#fff3e0,stroke:#e65100,stroke-width:2px
+    classDef platformStyle fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px
+
+    class UI,Widgets,Bloc uiStyle
+    class Data,API,Storage,Cache dataStyle
+    class Services,Audio,GPS,Geofence,Notif,Perms serviceStyle
+    class Platform,CarPlay,AndroidAuto platformStyle
+```
+
+## Conséquences
+
+### Positives
+- ✅ Aucune restriction licence commerciale (100% permissif)
+- ✅ Stack cohérent avec ADR-014 (Frontend Mobile)
+- ✅ Performance native (compilation ARM64 directe)
+- ✅ Écosystème mature et documenté
+- ✅ Support CarPlay/Android Auto via communauté
+- ✅ Conformité stores (permissions progressives)
+
+### Négatives
+- ⚠️ **CarPlay/Android Auto** : Packages communautaires (pas officiels Flutter)
+- ⚠️ **Géolocalisation background** : Scrutée par App Store (stratégie progressive requise, ADR-014)
+- ❌ **Courbe d'apprentissage** : Dart + pattern BLoC à maîtriser
+- ❌ **Tests stores** : Validation TestFlight (iOS) et Internal Testing (Android) obligatoires
+
+### Dépendances pubspec.yaml
+
+> **Note** : Les versions exactes seront définies lors de l'implémentation. Cette section indique les packages requis, non les versions à utiliser (qui évoluent rapidement dans l'écosystème Flutter).
+
+**Core** :
+- `flutter_bloc` - State management
+- `just_audio` - Audio HLS streaming
+- `dio` - HTTP client
+- `flutter_secure_storage` - Stockage sécurisé JWT
+- `cached_network_image` - Cache images
+
+**Géolocalisation & Notifications** :
+- `geolocator` - GPS haute précision
+- `geofence_service` - Geofencing arrière-plan
+- `flutter_local_notifications` - Notifications locales
+- `permission_handler` - Gestion permissions
+
+**CarPlay/Android Auto** (optionnels MVP) :
+- `flutter_carplay` - Intégration CarPlay
+- `android_auto_flutter` - Support Android Auto
+
+### Migration depuis ADR-014
+
+La section "Packages clés" de l'ADR-014 est désormais obsolète et doit référencer cet ADR :
+
+> **Packages Flutter** : Voir [ADR-022 - Librairies Flutter](020-librairies-flutter.md) pour la liste complète, licences et justifications.
+
+## Risques et Mitigations
+
+### Risque 1 : CarPlay/Android Auto packages communautaires
+- **Impact** : Maintenance non garantie par Flutter team
+- **Mitigation** : Fork privé si besoin, contribution upstream, ou développement custom si critique
+
+### Risque 2 : Validation App Store (permissions background)
+- **Impact** : Taux de rejet ~70% si mal justifié
+- **Mitigation** : Stratégie progressive (ADR-014), écrans d'éducation, tests beta TestFlight
+
+### Risque 3 : Performance audio HLS en arrière-plan
+- **Impact** : Interruptions si OS tue l'app
+- **Mitigation** : Background audio task iOS, foreground service Android (natif dans `just_audio`)
+
+## Références
+
+- ADR-014 : Frontend Mobile (Flutter, architecture permissions)
+- ADR-020 : Librairies Go (même format de documentation)
+- [flutter_bloc documentation](https://bloclibrary.dev/)
+- [just_audio repository](https://pub.dev/packages/just_audio)
+- [geolocator documentation](https://pub.dev/packages/geolocator)
+- [Apple CarPlay Developer Guide](https://developer.apple.com/carplay/)
+- [Android Auto Developer Guide](https://developer.android.com/training/cars)