geo/app/docs/SCAFFOLD-PLAN.md

# 📋 Plan de Migration - Architecture Super-Unifiée AppScaffold

## 🎯 Objectif
Créer une architecture unifiée avec un seul AppScaffold et des pages partagées entre admin/user, avec distinction visuelle par couleur (rouge pour admin / vert pour user).

## 🏗️ Vue d'ensemble de la nouvelle architecture

### Structure cible
```
lib/presentation/
├── widgets/
│   ├── app_scaffold.dart         # UNIQUE scaffold pour tous
│   └── dashboard_layout.dart     # Inchangé
├── pages/
│   ├── home_page.dart           # Unifié admin/user
│   ├── history_page.dart        # Unifié admin/user
│   ├── statistics_page.dart     # Unifié admin/user
│   ├── map_page.dart            # Unifié admin/user
│   ├── messages_page.dart       # Unifié admin/user
│   ├── field_mode_page.dart     # User seulement (role 1)
│   ├── amicale_page.dart        # Admin seulement (role 2)
│   └── operations_page.dart     # Admin seulement (role 2)
```

---

## 📝 Phase 1 : Créer AppScaffold unifié

### Objectif
Créer le composant central qui remplacera AdminScaffold et gérera les deux types d'utilisateurs.

### TODO
- [x] Créer `/lib/presentation/widgets/app_scaffold.dart`
- [x] Implémenter la classe `AppScaffold` avec :
  - [x] Détection automatique du rôle utilisateur
  - [x] Fond dégradé dynamique (rouge admin / vert user)
  - [x] Classe `DotsPainter` pour les points blancs décoratifs
  - [x] Intégration de `DashboardLayout`
- [x] Créer la classe `NavigationHelper` unifiée avec :
  - [x] `getDestinations(int userRole)` - destinations selon le rôle
  - [x] `navigateToIndex(BuildContext context, int index)` - navigation
  - [x] `getIndexFromRoute(String route)` - index depuis la route
- [x] Gérer les cas spéciaux :
  - [x] Vérification opération pour users (role 1)
  - [x] Vérification secteurs pour users (role 1)
  - [x] Messages d'erreur appropriés
- [x] Tester le scaffold avec un mock de page

### Notes
```dart
// Exemple de détection de rôle et couleur
final userRole = currentUser?.role ?? 1;  // role est un int dans UserModel
final isAdmin = userRole >= 2;
final gradientColors = isAdmin
  ? [Colors.white, Colors.red.shade300]    // Admin
  : [Colors.white, Colors.green.shade300];  // User
```

✅ **Phase 1 complétée avec succès !**
- AppScaffold créé avec détection automatique du rôle
- Fond dégradé rouge/vert selon le type d'utilisateur
- NavigationHelper centralisé
- Gestion des cas spéciaux (opération/secteurs)
- Page de test créée : `/lib/presentation/pages/test_page.dart`

---

## 📝 Phase 2 : Migrer la page History comme pilote

### Objectif
Créer la première page unifiée pour valider l'architecture.

### TODO
- [x] Créer `/lib/presentation/pages/history_page.dart`
- [x] Implémenter `HistoryPage` avec :
  - [x] Utilisation d'`AppScaffold`
  - [x] Paramètre optionnel `memberId` pour filtrage
- [x] Créer `HistoryContent` unifié avec :
  - [x] Détection du rôle utilisateur
  - [x] Logique conditionnelle pour les passages :
    - [x] Admin : tous les passages de l'opération courante
    - [x] User : seulement ses passages de l'opération courante
  - [x] Gestion des filtres selon le rôle :
    - [x] `showUserFilter: isAdmin` - filtre membre pour admin seulement
    - [x] `showSectorFilter: true` - disponible pour tous
    - [x] `showActions: isAdmin` - édition/suppression pour admin
    - [x] `showDateFilters: isAdmin` - dates début/fin pour admin
    - [x] `showPeriodFilter: !isAdmin` - période pour users
    - [x] `showAddButton: !isAdmin` - bouton ajout pour users
  - [x] Réutilisation de `PassagesListWidget`
- [x] Migrer la logique de sauvegarde des filtres dans Hive
- [ ] Tester les fonctionnalités :
  - [ ] Affichage des passages
  - [ ] Filtres
  - [ ] Actions (si admin)
  - [ ] Persistance des préférences

### Notes
```dart
// Structure de base de HistoryPage
class HistoryPage extends StatelessWidget {
  final int? memberId;

  @override
  Widget build(BuildContext context) {
    return AppScaffold(
      selectedIndex: 2,
      pageTitle: 'Historique',
      body: HistoryContent(memberId: memberId),
    );
  }
}
```

---

## 📝 Phase 3 : Valider avec les deux rôles

### Objectif
S'assurer que la page History fonctionne correctement pour les deux types d'utilisateurs.

### TODO

#### Tests avec compte User (role 1)
- [ ] Connexion avec un compte utilisateur standard
- [ ] Vérifier le fond dégradé vert
- [ ] Vérifier que seuls ses passages sont affichés
- [ ] Vérifier l'absence du filtre membre
- [ ] Vérifier l'absence des actions d'édition/suppression
- [ ] Tester les filtres disponibles (secteur, type, période)
- [ ] Vérifier la navigation

#### Tests avec compte Admin (role 2)
- [ ] Connexion avec un compte administrateur
- [ ] Vérifier le fond dégradé rouge
- [ ] Vérifier que tous les passages sont affichés
- [ ] Vérifier la présence du filtre membre
- [ ] Vérifier les actions d'édition/suppression
- [ ] Tester tous les filtres
- [ ] Vérifier la navigation étendue

#### Tests de performance
- [ ] Temps de chargement acceptable
- [ ] Fluidité du scrolling
- [ ] Réactivité des filtres
- [ ] Pas de rebuilds inutiles

#### Corrections identifiées
- [ ] Liste des bugs trouvés
- [ ] Corrections appliquées
- [ ] Re-test après corrections

---

## 📝 Phase 4 : Migrer les autres pages progressivement

### Objectif
Appliquer le pattern validé aux autres pages de l'application.

### 4.1 HomePage
- [ ] Créer `/lib/presentation/pages/home_page.dart`
- [ ] Créer `HomePage` avec `AppScaffold`
- [ ] Créer `HomeContent` unifié avec :
  - [ ] Titre dynamique selon le rôle
  - [ ] `PassageSummaryCard` avec `showAllPassages: isAdmin`
  - [ ] `PaymentSummaryCard` avec filtrage selon rôle
  - [ ] `MembersBoardPassages` seulement si `isAdmin && kIsWeb`
  - [ ] `SectorDistributionCard` avec `showAllSectors: isAdmin`
  - [ ] `ActivityChart` avec `showAllPassages: isAdmin`
  - [ ] Actions rapides seulement si `isAdmin && kIsWeb`
- [ ] Tester avec les deux rôles

### 4.2 StatisticsPage
- [ ] Créer `/lib/presentation/pages/statistics_page.dart`
- [ ] Créer `StatisticsPage` avec `AppScaffold`
- [ ] Créer `StatisticsContent` unifié avec :
  - [ ] Graphiques filtrés selon le rôle
  - [ ] Statistiques globales (admin) vs personnelles (user)
  - [ ] Export de données si admin
- [ ] Tester avec les deux rôles

### 4.3 MapPage
- [ ] Créer `/lib/presentation/pages/map_page.dart`
- [ ] Créer `MapPage` avec `AppScaffold`
- [ ] Créer `MapContent` unifié avec :
  - [ ] Secteurs filtrés selon le rôle
  - [ ] Marqueurs de passages filtrés
  - [ ] Actions d'édition si admin
- [ ] Tester avec les deux rôles

### 4.4 MessagesPage
- [ ] Créer `/lib/presentation/pages/messages_page.dart`
- [ ] Migrer depuis `chat_communication_page.dart`
- [ ] Créer `MessagesPage` avec `AppScaffold`
- [ ] Adapter le chat (identique pour tous les rôles)
- [ ] Tester avec les deux rôles

### 4.5 Pages spécifiques (non unifiées)
#### FieldModePage (User uniquement)
- [ ] Garder dans `/lib/presentation/user/user_field_mode_page.dart`
- [ ] Adapter pour utiliser `AppScaffold`
- [ ] Masquer pour les admins dans la navigation

#### AmicalePage (Admin uniquement)
- [ ] Garder dans `/lib/presentation/admin/admin_amicale_page.dart`
- [ ] Adapter pour utiliser `AppScaffold`
- [ ] Masquer pour les users dans la navigation

#### OperationsPage (Admin uniquement)
- [ ] Garder dans `/lib/presentation/admin/admin_operations_page.dart`
- [ ] Adapter pour utiliser `AppScaffold`
- [ ] Masquer pour les users dans la navigation

---

## 📝 Phase 5 : Nettoyer l'ancien code

### Objectif
Supprimer tout le code obsolète après la migration complète.

### TODO

#### Supprimer les anciens scaffolds
- [ ] Supprimer `/lib/presentation/widgets/admin_scaffold.dart`
- [ ] Supprimer les références à `AdminScaffold`

#### Supprimer les anciennes pages user
- [ ] Supprimer `/lib/presentation/user/user_dashboard_page.dart`
- [ ] Supprimer `/lib/presentation/user/user_dashboard_home_page.dart`
- [ ] Supprimer `/lib/presentation/user/user_history_page.dart`
- [ ] Supprimer `/lib/presentation/user/user_statistics_page.dart`
- [ ] Supprimer `/lib/presentation/user/user_map_page.dart`

#### Supprimer les anciennes pages admin
- [ ] Supprimer `/lib/presentation/admin/admin_home_page.dart`
- [ ] Supprimer `/lib/presentation/admin/admin_history_page.dart`
- [ ] Supprimer `/lib/presentation/admin/admin_statistics_page.dart`
- [ ] Supprimer `/lib/presentation/admin/admin_map_page.dart`

#### Nettoyer les imports
- [ ] Rechercher et supprimer tous les imports obsolètes
- [ ] Vérifier qu'il n'y a pas de références mortes

#### Vérifier la compilation
- [ ] `flutter analyze` sans erreurs
- [ ] `flutter build` réussi

---

## 📝 Phase 6 : Mettre à jour le routing GoRouter

### Objectif
Adapter le système de routing pour la nouvelle architecture unifiée.

### TODO

#### Modifier les routes principales
- [ ] Mettre à jour `/lib/core/navigation/app_router.dart` (ou équivalent)
- [ ] Routes unifiées :
  - [ ] `/` ou `/home` → `HomePage` (admin et user)
  - [ ] `/history` → `HistoryPage` (admin et user)
  - [ ] `/statistics` → `StatisticsPage` (admin et user)
  - [ ] `/map` → `MapPage` (admin et user)
  - [ ] `/messages` → `MessagesPage` (admin et user)
- [ ] Routes spécifiques :
  - [ ] `/field-mode` → `FieldModePage` (user seulement)
  - [ ] `/amicale` → `AmicalePage` (admin seulement)
  - [ ] `/operations` → `OperationsPage` (admin seulement)

#### Implémenter les guards de navigation
- [ ] Créer un guard pour vérifier le rôle
- [ ] Rediriger si accès non autorisé :
  - [ ] User vers `/field-mode` → OK
  - [ ] User vers `/amicale` → Redirection vers `/home`
  - [ ] Admin vers `/field-mode` → Redirection vers `/home`
- [ ] Gérer les cas spéciaux :
  - [ ] Pas d'opération → Message approprié
  - [ ] Pas de secteur → Message approprié

#### Mettre à jour la navigation
- [ ] Adapter `NavigationHelper.navigateToIndex()`
- [ ] Vérifier tous les `context.go()` et `context.push()`
- [ ] S'assurer que les deep links fonctionnent

#### Tests de navigation
- [ ] Tester toutes les routes avec user
- [ ] Tester toutes les routes avec admin
- [ ] Tester les redirections non autorisées
- [ ] Tester les deep links
- [ ] Tester le bouton retour

---

## 📊 Suivi de progression

### Résumé
- [ ] Phase 1 : AppScaffold unifié
- [ ] Phase 2 : Page History pilote
- [ ] Phase 3 : Validation deux rôles
- [ ] Phase 4 : Migration autres pages
- [ ] Phase 5 : Nettoyage code obsolète
- [ ] Phase 6 : Mise à jour routing

### Métriques
- **Fichiers créés** : 9/10 (app_scaffold.dart, test_page.dart, history_page.dart, home_page.dart, statistics_page.dart, map_page.dart, messages_page.dart, field_mode_page.dart + corrections)
- **Fichiers supprimés** : 0/14
- **Pages migrées** : 5/5 ✅ (History, Home, Statistics, Map, Messages)
- **Routing unifié** : ✅ Complété pour user et admin
- **Navigation directe** : ✅ Plus de double imbrication
- **Tests validés** : 1/20 (scaffold de base)
- **Phase 1** : ✅ Complétée
- **Phase 2** : ✅ Complétée
- **Phase 4** : ✅ Complétée

### Notes et observations
```
- Phase 1 : AppScaffold créé avec succès, détection automatique du rôle fonctionnelle
- Phase 2 : HistoryPage unifiée créée avec référence à admin_history_page.dart
  - Utilisation de dates début/fin au lieu du select période pour les admins
  - Filtres adaptatifs selon le rôle (membre, dates pour admin / période pour users)
  - Intégration réussie avec PassagesListWidget existant
  - Correction des types : role est un int, montant est un String
  - getUserSectors() au lieu de getAllUserSectors() (méthode inexistante)
- Phase 2 (suite) : Uniformisation complète de l'interface
  - Titre unique "Historique des passages" pour tous
  - Filtres dates (début/fin) disponibles pour TOUS (admin ET user)
  - Suppression du filtre période (doublon)
  - Permissions adaptatives :
    * Admin : voir tout, filtrer par membre, ajouter/éditer/supprimer tout
    * User : voir ses passages, ajouter, éditer ses passages, supprimer si chkUserDeletePass=true
  - Modification de user_dashboard_page.dart pour utiliser la nouvelle page unifiée
  - Correction du type de role (int au lieu de String) dans user_dashboard_page.dart
- Routing unifié pour user (comme admin) :
  - Ajout de sous-routes : /user/dashboard, /user/history, /user/statistics, etc.
  - Même architecture de navigation que /admin/*
  - Navigation par URL directe maintenant possible
  - NavigationHelper mis à jour pour utiliser les nouvelles routes
  - Imports ajoutés dans app.dart pour toutes les pages user
- Phase 4 (HomePage) : Page Home unifiée créée
  - Basée sur admin_home_page.dart
  - Utilise AppScaffold avec détection de rôle
  - Widgets conditionnels :
    * PassageSummaryCard : titre adaptatif "Passages" vs "Mes passages"
    * PaymentSummaryCard : titre adaptatif "Règlements" vs "Mes règlements"
    * MembersBoardPassages : admin seulement (sur web)
    * SectorDistributionCard : filtre automatique selon rôle
    * ActivityChart : showAllPassages selon rôle
    * Actions rapides : admin seulement (sur web)
  - Routes mises à jour : /admin et /user/dashboard utilisent HomePage
  - Suppression des imports non utilisés (admin_home_page, user_dashboard_home_page)
- Correction double imbrication navigation :
  - Problème : UserDashboardPage contenait les pages qui utilisent AppScaffold = double nav
  - Solution : Navigation directe vers les pages (HomePage, HistoryPage, etc.)
  - Création de pages unifiées avec AppScaffold :
    * StatisticsPage (placeholder)
    * MapPage (placeholder)
    * MessagesPage (utilise ChatCommunicationPage)
    * FieldModePage (utilise UserFieldModePage)
  - Routes /user/* pointent directement vers les pages unifiées
  - Plus besoin de UserDashboardPage comme conteneur
```

---

## ✅ Critères de succès

1. **Architecture simplifiée** : Un seul scaffold, pages unifiées
2. **Performance maintenue** : Pas de dégradation notable
3. **UX améliorée** : Distinction visuelle claire (rouge/vert)
4. **Code DRY** : Pas de duplication
5. **Tests passants** : Tous les scénarios validés
6. **Documentation** : Code bien commenté et documenté

---

*Document créé le : 26/09/2025*
*Dernière mise à jour : 26/09/2025*