geo/docs/architecture.md

Architecture de GEOSECTOR

Description générale

GEOSECTOR est une application Flutter conçue pour la gestion de secteurs géographiques et de passages. L'application suit une architecture modulaire qui sépare clairement les préoccupations et permet une maintenance facilitée. Elle utilise un pattern de conception proche du MVVM (Model-View-ViewModel) avec des instances globales pour la gestion d'état et l'accès aux services.

Structure du projet

L'application est organisée selon une architecture en couches avec une séparation claire des responsabilités :

lib/
├── app.dart                 # Point d'entrée de l'application
├── main.dart                # Configuration initiale
├── core/                    # Fonctionnalités communes et services de base
│   ├── constants/           # Constantes de l'application
│   ├── data/                # Modèles de données
│   │   └── models/          # Définitions des modèles pour Hive
│   ├── providers/           # Providers pour l'injection de dépendances
│   ├── repositories/        # Gestion des données et logique métier
│   ├── routes/              # Configuration du routage
│   ├── services/            # Services d'infrastructure
│   ├── theme/               # Thème de l'application
│   └── widgets/             # Widgets communs réutilisables
├── presentation/            # Interface utilisateur par module
│   ├── admin/               # Écrans d'administration
│   ├── auth/                # Écrans d'authentification
│   ├── public/              # Écrans publics
│   ├── user/                # Écrans utilisateur
│   └── widgets/             # Widgets partagés pour l'UI
└── shared/                  # Ressources partagées
    ├── app_theme.dart       # Configuration du thème
    └── widgets/             # Widgets partagés entre modules

Couches d'architecture

1. Couche de présentation (Presentation Layer)

La couche de présentation est responsable de l'interface utilisateur et est divisée en modules fonctionnels :

• admin/ : Pages du tableau de bord administrateur
• auth/ : Pages d'authentification (login, register)
• public/ : Pages accessibles sans authentification
• user/ : Pages du tableau de bord utilisateur
• widgets/ : Composants UI partagés entre les modules

Chaque module de présentation suit une structure cohérente avec des pages distinctes pour chaque fonctionnalité principale :

user/
├── user_dashboard_page.dart         # Page principale avec navigation
├── user_dashboard_home_page.dart    # Accueil du tableau de bord
├── user_map_page.dart               # Carte et secteurs
├── user_history_page.dart           # Historique des passages
├── user_statistics_page.dart        # Statistiques et graphiques
└── user_communication_page.dart     # Communication interne

De même, le module admin suit une structure similaire avec des pages spécifiques :

admin/
├── admin_dashboard_page.dart        # Page principale avec navigation
├── admin_dashboard_home_page.dart   # Accueil du tableau de bord admin
├── admin_map_page.dart              # Gestion des cartes et secteurs
├── admin_history_page.dart          # Historique global des passages
├── admin_statistics_page.dart       # Statistiques avancées
├── admin_communication_page.dart    # Gestion des communications
└── admin_entite.dart                # Gestion des amicales et membres

2. Couche de données (Data Layer)

La couche de données est responsable de la gestion des données et comprend :

• models/ : Modèles de données avec adaptateurs Hive pour la persistance locale

  • user_model.dart : Données utilisateur et authentification
  • operation_model.dart : Opérations et campagnes
  • sector_model.dart : Secteurs géographiques
  • passage_model.dart : Données des passages
  • membre_model.dart : Données des membres pour l'interface admin

• repositories/ : Gestionnaires de données pour chaque domaine

  • user_repository.dart : Gestion des utilisateurs et authentification
  • operation_repository.dart : Gestion des opérations
  • passage_repository.dart : Gestion des passages
  • sector_repository.dart : Gestion des secteurs
  • membre_repository.dart : Gestion des membres pour l'interface admin

3. Couche de services (Services Layer)

La couche de services fournit des fonctionnalités d'infrastructure et d'intégration :

• api_service.dart : Communication avec l'API backend
• auth_service.dart : Gestion de l'authentification
• connectivity_service.dart : Surveillance de la connectivité réseau
• location_service.dart : Services de géolocalisation
• passage_data_service.dart : Traitement des données de passage
• sync_service.dart : Synchronisation des données locales/serveur

Gestion d'état et injection de dépendances

L'application utilise des instances globales pour la gestion d'état et l'accès aux services. Ces instances sont définies dans le fichier app.dart :

// Instances globales des services et repositories
final apiService = ApiService();
final operationRepository = OperationRepository(apiService);
final passageRepository = PassageRepository(apiService);
final userRepository = UserRepository(apiService);
final sectorRepository = SectorRepository(apiService);
final membreRepository = MembreRepository(apiService);
final syncService = SyncService(userRepository: userRepository);
final connectivityService = ConnectivityService();

Le widget AppProviders a été maintenu pour la compatibilité, mais il retourne simplement l'enfant sans utiliser Provider :

class AppProviders extends StatelessWidget {
  final Widget child;

  const AppProviders({
    Key? key,
    required this.child,
  }) : super(key: key);

  @override
  Widget build(BuildContext context) {
    // Les instances globales sont maintenant définies dans app.dart
    // Cette classe est maintenue pour la compatibilité
    return child;
  }
}

Cette approche permet :

1. De simplifier l'architecture en éliminant la dépendance à Provider
2. D'accéder directement aux services et repositories depuis n'importe quel widget
3. De réduire la complexité du code et d'améliorer les performances
4. De maintenir une séparation claire des responsabilités

Routage et navigation

L'application utilise go_router pour la gestion des routes et de la navigation :

• AppRouter : Configuration centralisée des routes de l'application
• Redirections conditionnelles : Contrôle d'accès basé sur l'état d'authentification
• Persistance de parcours : Sauvegarde du dernier chemin de l'utilisateur

Le système de routage implémente :

• Redirection basée sur les rôles (admin vs utilisateur)
• Gestion des sessions persistantes
• Navigation entre les différentes sections de l'application

Persistance des données

L'application utilise Hive pour la persistance locale des données :

• Initialisation sélective : Ouverture des boîtes Hive à la demande
• Gestion efficace de la mémoire : Optimisation de l'utilisation des ressources
• Mode hors ligne : Fonctionnalité complète même sans connexion Internet

La gestion des boîtes Hive est optimisée selon ces principes :

• Ouverture des boîtes essentielles au démarrage (users, settings)
• Ouverture des autres boîtes (operations, sectors, passages, membres) après connexion
• Nettoyage et recréation des boîtes sans les fermer lors de la déconnexion

Intégrations externes

L'application intègre plusieurs services externes :

• Mapbox : Affichage des cartes et gestion des secteurs géographiques
• Stripe : Traitement des paiements en ligne
• API FulRest PHP : Communication avec le backend
• Base de données MariaDB : Stockage centralisé des données

Sécurité

L'application implémente plusieurs mesures de sécurité :

• Chiffrement Argon2 pour les mots de passe
• Chiffrement AES-256 pour les données sensibles
• Session PHP pour l'authentification API
• Mécanismes de contrôle d'accès basés sur les rôles

Flux d'authentification

Le flux d'authentification suit ce processus :

1. Vérification initiale de session persistante (Hive)
2. Redirection vers Login/Register si nécessaire
3. Authentification via API Service
4. Stockage sécurisé des informations de session
5. Redirection vers l'interface appropriée (admin vs utilisateur)

Widgets communs

L'application utilise plusieurs widgets communs pour maintenir une cohérence d'interface :

1. Widget Carte MapBox : Affichage/édition de secteurs et marqueurs
2. Widget Formulaire de passage : Saisie des données de passage
3. Widget Historique : Liste des passages avec filtres et tri
   • Filtrage par type de passage (avec possibilité d'exclure certains types)
   • Filtrage par utilisateur (pour les administrateurs)
   • Filtrage par secteur (pour les administrateurs)
   • Filtrage par période (derniers 15 jours, dernière semaine, dernier mois, personnalisé)
   • Recherche textuelle (adresse, nom, notes)
   • Interface adaptative (compacte pour desktop, étendue pour mobile)
4. Widget Statistiques : Visualisation graphique des données

Widget PassagesListWidget

Le widget PassagesListWidget est un composant réutilisable qui permet d'afficher une liste de passages avec des fonctionnalités avancées de filtrage :

PassagesListWidget(
  passages: formattedPassages,
  showFilters: true,
  showSearch: true,
  showActions: true,
  initialSearchQuery: searchQuery,
  initialTypeFilter: selectedType,
  initialPaymentFilter: selectedPaymentMethod,
  // Filtres avancés
  excludePassageTypes: [2], // Exclure les passages "À finaliser"
  filterByUserId: selectedUserId, // Filtrer par utilisateur
  filterBySectorId: selectedSectorId, // Filtrer par secteur
  periodFilter: 'lastMonth', // Période par défaut
  dateRange: selectedDateRange, // Plage de dates personnalisée
  // Callbacks
  onPassageSelected: (passage) => _showDetailsDialog(context, passage),
  onReceiptView: (passage) => _showReceiptDialog(context, passage),
  onDetailsView: (passage) => _showDetailsDialog(context, passage),
  onPassageEdit: (passage) => _editPassage(passage),
)

Ce widget est utilisé dans plusieurs pages de l'application :

• user_dashboard_home_page.dart : Affiche les derniers passages de l'utilisateur courant
• user_history_page.dart : Affiche l'historique complet des passages de l'utilisateur courant
• admin_history_page.dart : Affiche l'historique global de tous les passages avec des filtres avancés

Relations avec d'autres composants

• Backend API : Communication via ApiService pour toutes les opérations CRUD
• Stockage local : Utilisation de Hive pour la persistance des données
• Services externes : Intégration avec Mapbox, Stripe et autres services tiers

Bonnes pratiques implémentées

1. Séparation des préoccupations : Découpage clair entre UI, logique métier et données
2. Accès simplifié aux services : Utilisation d'instances globales pour un accès direct aux services
3. Mode hors ligne : Fonctionnalité complète même sans connexion Internet
4. Thème cohérent : Application d'un thème unifié via AppTheme
5. Routage centralisé : Gestion des redirections et autorisations d'accès