mobile/documentation/CDC_App_Flutter.md

# Cahier des Charges — Application Utilisateur Mobile & Web
## Projet : Laverie Connectée — App Flutter
**Version :** 1.0  
**Date :** 2026-06-27  
**Stack principale :** Flutter 3.x (Android / iOS / Web)

---

## 1. Contexte & Objectifs

### 1.1 Contexte
Application grand public permettant aux utilisateurs de :
- Localiser les laveries disponibles
- Gérer leur porte-monnaie électronique
- Réserver un créneau machine
- Déclencher un lavage par QR code
- Suivre leurs lavages et consulter leur historique

### 1.2 Cibles plateformes
| Plateforme | Version minimale | Distribution |
|------------|-----------------|--------------|
| Android | 8.0 (API 26) | Google Play Store |
| iOS | 15.0 | Apple App Store |
| Web | Chrome 100+, Safari 15+, Firefox 100+ | PWA hébergée |

### 1.3 Contraintes
- L'app doit rester **utilisable hors-ligne** pour les fonctions de consultation (solde en cache, historique)
- Respect strict du **RGPD** : collecte minimale, consentements explicites, droit à l'effacement
- L'application doit rester **connectée en arrière-plan** pour recevoir les notifications push

---

## 2. Stack Technique

| Composant | Technologie | Version | Justification |
|-----------|-------------|---------|---------------|
| Framework UI | Flutter | 3.x (stable) | Codebase unique Android/iOS/Web |
| Langage | Dart | 3.x | Null-safety, typage fort |
| State management | Riverpod | 2.x | Réactivité, testabilité, pas de BuildContext dependency |
| Navigation | GoRouter | 13.x | Deep links, routing déclaratif |
| HTTP Client | Dio | 5.x | Intercepteurs JWT, retry automatique |
| Cache local | Hive | 2.x | Clé-valeur rapide, offline-first |
| Auth persistence | flutter_secure_storage | 9.x | Stockage sécurisé tokens (Keychain / Keystore) |
| Notifications push | firebase_messaging | 15.x | FCM Android/Web + APNs iOS |
| QR Code scan | mobile_scanner | 5.x | Caméra native, performant |
| Paiement in-app | flutter_stripe | 10.x | Stripe SDK officiel |
| Géolocalisation | geolocator | 13.x | Localisation établissements |
| Cartes | flutter_map + OpenStreetMap | — | Affichage carte sans coût API Google |
| Internationalisation | flutter_localizations | (Flutter) | fr / en au minimum |
| Tests | flutter_test + Mockito | — | Unit + widget + integration tests |
| CI/CD | GitHub Actions + Fastlane | — | Build, test, déploiement stores |
| Monitoring | Firebase Crashlytics | — | Crashes prod |
| Analytics | Firebase Analytics | — | Entonnoirs, rétention |

---

## 3. Architecture de l'Application

### 3.1 Pattern architectural : Clean Architecture + Feature-first

```
lib/
├── core/
│   ├── api/
│   │   ├── api_client.dart          # Instance Dio configurée
│   │   ├── interceptors/
│   │   │   ├── auth_interceptor.dart    # Injection Bearer token
│   │   │   └── retry_interceptor.dart   # Retry sur 401 avec refresh
│   │   └── api_exception.dart
│   ├── cache/
│   │   └── hive_service.dart        # Abstraction cache local
│   ├── router/
│   │   └── app_router.dart          # GoRouter centralisé
│   ├── theme/
│   │   ├── app_theme.dart
│   │   └── app_colors.dart
│   └── utils/
│       ├── currency_formatter.dart
│       └── date_formatter.dart
│
├── features/
│   ├── auth/
│   │   ├── data/
│   │   │   ├── auth_repository.dart
│   │   │   └── models/auth_token.dart
│   │   ├── domain/
│   │   │   └── providers/auth_provider.dart
│   │   └── presentation/
│   │       ├── login_screen.dart
│   │       └── register_screen.dart
│   │
│   ├── wallet/
│   │   ├── data/
│   │   ├── domain/
│   │   └── presentation/
│   │       ├── wallet_screen.dart
│   │       ├── transaction_history_screen.dart
│   │       └── top_up_screen.dart
│   │
│   ├── establishments/
│   │   ├── data/
│   │   ├── domain/
│   │   └── presentation/
│   │       ├── map_screen.dart
│   │       ├── establishment_list_screen.dart
│   │       └── establishment_detail_screen.dart
│   │
│   ├── machines/
│   │   ├── data/
│   │   ├── domain/
│   │   └── presentation/
│   │       ├── machine_card_widget.dart
│   │       └── machine_detail_screen.dart
│   │
│   ├── booking/
│   │   ├── data/
│   │   ├── domain/
│   │   └── presentation/
│   │       ├── slot_picker_screen.dart
│   │       ├── booking_confirm_screen.dart
│   │       └── my_bookings_screen.dart
│   │
│   ├── wash/
│   │   ├── data/
│   │   ├── domain/
│   │   └── presentation/
│   │       ├── qr_scanner_screen.dart
│   │       ├── wash_confirm_screen.dart
│   │       └── wash_active_screen.dart
│   │
│   ├── notifications/
│   │   └── notification_service.dart
│   │
│   └── profile/
│       └── presentation/
│           ├── profile_screen.dart
│           └── gdpr_settings_screen.dart
│
└── main.dart
```

### 3.2 Flux d'authentification

```
App start
  └── AuthProvider.check()
        ├── Token valide → HomeScreen
        ├── Token expiré → RefreshToken()
        │       ├── Succès → HomeScreen
        │       └── Échec → LoginScreen
        └── Pas de token → OnboardingScreen
```

### 3.3 Gestion du token JWT

- `AuthInterceptor` (Dio) : inject `Authorization: Bearer <token>` sur chaque requête
- Sur 401 : appel automatique à `/auth/refresh` → retry de la requête originale
- Tokens stockés dans `flutter_secure_storage` (Keychain iOS / Keystore Android)
- Sur Web : stockage en `sessionStorage` chiffré (pas de `localStorage` pour les tokens)

---

## 4. Écrans & Parcours Utilisateur

### 4.1 Navigation principale (Bottom Navigation Bar)

```
┌─────────────────────────────────────────────┐
│  🗺 Carte  │  💰 Wallet  │  📅 Réservations  │  👤 Profil │
└─────────────────────────────────────────────┘
```

### 4.2 Onboarding & Inscription

**Écran 1 — Bienvenue**
- Logo + baseline
- CTA : "Se connecter" / "Créer un compte"

**Écran 2 — Inscription (multi-étapes)**
- Étape 1 : Email + mot de passe (+ confirmation)
- Étape 2 : Prénom, nom, téléphone, date de naissance
- Étape 3 : Consentements RGPD (cases à cocher individuelles, non pré-cochées)
  - Traitement des données (obligatoire)
  - Communications marketing (optionnel)
  - Analyse d'utilisation (optionnel)
- Étape 4 : Code parrainage (optionnel)
- Confirmation email requise avant accès complet

**Règles de validation :**
- Email : format RFC 5322
- Mot de passe : 8 caractères minimum, 1 majuscule, 1 chiffre
- Téléphone : format E.164 (`+33XXXXXXXXX`)
- Date de naissance : 16 ans minimum

### 4.3 Carte & Établissements

**Écran Carte (`MapScreen`)**
- Carte OpenStreetMap centrée sur la position utilisateur
- Marqueurs pour chaque établissement (couleur selon disponibilité)
  - 🟢 Machines disponibles
  - 🟡 Toutes occupées, créneaux libres
  - 🔴 Toutes occupées, aucun créneau proche
- Tap sur marqueur → sheet inférieure avec résumé
- Bouton liste (switch vue liste / carte)

**Écran Détail Établissement**
- Nom, adresse, horaires
- Liste des machines avec statut temps réel (polling 30s ou WebSocket si dispo)
- Pour chaque machine : type, statut, prochain créneau libre, tarif actuel
- CTA : "Réserver" ou "Scanner & Lancer"

### 4.4 Porte-monnaie

**Écran Wallet**
- Solde affiché en grand (avec animation de mise à jour)
- Bouton "Recharger" bien visible
- Historique des 10 dernières transactions
- Lien "Voir tout"

**Écran Historique**
- Liste paginée (infinite scroll)
- Filtres : Type (débit/crédit), Période
- Chaque entrée : icône type, montant coloré, source, date/heure, solde après
- Export CSV (optionnel, v2)

**Parcours Rechargement**
1. Saisie du montant (suggestions : 10€, 20€, 50€)
2. Sélection du fournisseur de paiement (si plusieurs disponibles)
3. Redirection vers Stripe Checkout (WebView sécurisée) ou SDK natif
4. Retour sur l'app via deep link `laverie://wallet/topup-result`
5. Confirmation animée + mise à jour du solde
6. Notification push de confirmation

**Contraintes :**
- Montant minimum : 5€, maximum : 150€ par rechargement
- Affichage du solde en cache si hors-ligne

### 4.5 Réservation d'un Créneau

**Écran Sélection de Créneau (`SlotPickerScreen`)**
- Sélecteur de date (calendrier scrollable, 14 jours maximum)
- Pour la date sélectionnée : grille horaire avec créneaux libres/occupés
- Mise en évidence du prix par créneau (heure creuse / heure pleine)
- Information : "Supplément réservation : +1.00€"

**Écran Confirmation Réservation**
- Récapitulatif : machine, date/heure, durée, prix total
- Solde actuel et solde après débit
- Mention pénalité no-show
- Bouton "Confirmer et débiter X.XX€"

**Écran Mes Réservations**
- Onglets : À venir / Passées
- Chaque réservation : statut badge, machine, créneau, montant
- Actions possibles : "Annuler", "Déplacer" (si > 2h)
- Countdown pour les réservations imminentes

**Règles métier UI :**
- Créneau non réservable si solde insuffisant → CTA "Recharger d'abord"
- Annulation : popup de confirmation avec montant remboursé affiché
- Déplacement : ouvre SlotPickerScreen avec le même contexte machine

### 4.6 Déclenchement d'un Lavage par QR Code

**Écran Scanner QR (`QrScannerScreen`)**
- Vue caméra plein écran avec cadre de scan
- Feedback visuel à la détection (vibration + flash vert)
- Fallback : saisie manuelle du code machine

**Flux post-scan :**
1. Identification de la machine via le QR
2. Appel API → vérification statut + tarif
3. Affichage récap : machine, programme, prix estimé, solde après
4. Bouton "Lancer le lavage"
5. Animation de confirmation (spinner → ✓)
6. Écran "Lavage en cours" avec countdown

**Écran Lavage Actif (`WashActiveScreen`)**
- Machine + établissement
- Barre de progression avec temps restant (mise à jour polling API 30s)
- Montant débité
- Notification push à la fin du cycle

### 4.7 Notifications Push

**Configuration :**
- Demande de permission notifications à l'inscription (après onboarding)
- Sur iOS : `UNUserNotificationCenter.requestAuthorization`
- Sur Android 13+ : `POST_NOTIFICATIONS` permission
- Token FCM/APNs envoyé à l'API à chaque démarrage de l'app (mise à jour si changé)

**Gestion en foreground :**
- Affichage d'une bannière in-app (snackbar stylisée)
- Tap → navigation vers l'écran pertinent

**Deep links depuis notification :**
| Notification | Deep link |
|---|---|
| Rechargement confirmé | `laverie://wallet` |
| Réservation confirmée | `laverie://bookings/{uuid}` |
| Rappel créneau | `laverie://bookings/{uuid}` |
| Lavage terminé | `laverie://washes/{uuid}` |
| Promo disponible | `laverie://establishments/{uuid}` |

### 4.8 Profil & Paramètres

**Écran Profil**
- Informations personnelles (modifiables)
- Mes statistiques : nombre de lavages, total dépensé, économies promos
- Code parrainage personnel (copiable, partageable)
- Gestion notifications (toggle par type)
- Paramètres RGPD
- Déconnexion

**Écran Paramètres RGPD**
- Visualisation des consentements donnés (avec date)
- Toggle individuel pour chaque consentement
- Bouton "Télécharger mes données" (export JSON, v2)
- Bouton "Supprimer mon compte" (confirmation en deux étapes + délai 30 jours)

---

## 5. Gestion de l'État (Riverpod)

### 5.1 Providers principaux

```dart
// Auth
final authProvider = StateNotifierProvider<AuthNotifier, AuthState>

// Wallet
final walletProvider = FutureProvider<WalletData>
final transactionsProvider = StateNotifierProvider<TransactionsNotifier, TransactionsState>

// Establishments
final establishmentsProvider = FutureProvider.family<Establishment, String>  // by uuid
final nearbyEstablishmentsProvider = FutureProvider<List<Establishment>>

// Machines
final machineStatusProvider = StreamProvider.family<Machine, String>  // polling 30s

// Bookings
final bookingsProvider = StateNotifierProvider<BookingsNotifier, BookingsState>
final slotAvailabilityProvider = FutureProvider.family<List<TimeSlot>, SlotQuery>

// Active wash
final activeWashProvider = StreamProvider<Wash?>  // null si aucun lavage en cours
```

### 5.2 Stratégie offline-first (Hive)

| Donnée | Cache | TTL |
|--------|-------|-----|
| Solde wallet | Oui | Jusqu'au prochain refresh |
| Historique transactions | Oui (50 dernières) | 24h |
| Établissements (liste) | Oui | 1h |
| Disponibilités machines | Non | — |
| Réservations | Oui | 30 min |

En cas d'absence de réseau : affichage des données en cache avec badge "Données hors-ligne".

---

## 6. Sécurité

### 6.1 Stockage
- Tokens JWT : `flutter_secure_storage` (AES-256 sur Android, Keychain sur iOS)
- Aucune donnée sensible dans `SharedPreferences`
- Sur Web : pas de localStorage, session uniquement

### 6.2 Réseau
- Certificate pinning en production (via `dio` custom `HttpClient`)
- Timeout : 10s connexion, 30s réception
- Toutes les requêtes en HTTPS (TLS 1.3)

### 6.3 QR Code
- Vérification côté serveur (le QR code seul ne suffit pas à déclencher un lavage)
- Rate limiting API sur `/washes/start` : 3 req/min/user

---

## 7. Performance & UX

- **Splash screen** natif (Android 12 Splash API, iOS UILaunchScreen)
- **Skeleton loaders** sur toutes les listes et cartes pendant le chargement
- **Optimistic UI** : affichage anticipé des mises à jour (ex: annulation réservation)
- **Pull-to-refresh** sur toutes les listes
- **Pagination infinie** sur l'historique des transactions
- **Animations** : transitions de pages fluides (Hero, Fade), animation solde wallet

---

## 8. Tests

| Type | Outil | Portée |
|------|-------|--------|
| Tests unitaires | `flutter_test` | Providers Riverpod, formatters, validators |
| Tests widgets | `flutter_test` | Tous les écrans principaux |
| Tests d'intégration | `integration_test` | Parcours critiques (inscription, rechargement, scan QR) |
| Tests golden | `golden_toolkit` | Composants UI clés (cohérence visuelle) |

**Parcours critiques à couvrir en intégration :**
1. Inscription complète → vérification email → connexion
2. Rechargement porte-monnaie (mock Stripe)
3. Réservation créneau → annulation → vérification remboursement
4. Scan QR → lancement lavage → fin de cycle

---

## 9. CI/CD

### 9.1 Pipeline GitHub Actions

```yaml
# Sur chaque PR :
- flutter analyze          # Linting strict
- flutter test             # Tests unitaires + widgets
- flutter build apk --release   # Vérification build Android
- flutter build ios --release   # Vérification build iOS (macOS runner)
- flutter build web             # Vérification build Web

# Sur merge main :
- Fastlane → TestFlight (iOS)
- Fastlane → Play Store Internal Track (Android)
- Deploy Web → hébergement (Firebase Hosting ou VPS)
```

### 9.2 Flavors

| Flavor | API URL | Firebase projet | Build suffix |
|--------|---------|-----------------|--------------|
| dev | `http://localhost:8000` | laverie-dev | `.dev` |
| staging | `https://api-staging.laverie.app` | laverie-staging | `.staging` |
| production | `https://api.laverie.app` | laverie-prod | — |

---

## 10. Livrables attendus

- [ ] Code source Flutter (GitHub, repository dédié)
- [ ] Flavors configurés (dev / staging / prod)
- [ ] `README.md` avec instructions setup complet
- [ ] Fichiers de configuration Firebase (`google-services.json`, `GoogleService-Info.plist`)
- [ ] Fichiers de signature Android (`.keystore`) documentés
- [ ] Screenshots pour les stores (5 par plateforme minimum)
- [ ] Suite de tests (couverture > 70% sur la logique métier)
- [ ] Build release Android (`.aab`) + iOS (`.ipa`) prêts à soumettre