unionflow-server-impl-quarkus/unionflow-mobile-apps/lib/features/dashboard/README.md

Dashboard Module - Architecture Modulaire

📁 Structure des Fichiers

dashboard/
├── presentation/
│   ├── pages/
│   │   └── dashboard_page_stable.dart          # Page principale du dashboard
│   └── widgets/
│       ├── widgets.dart                        # Index des exports
│       ├── dashboard_welcome_section.dart      # Section de bienvenue
│       ├── dashboard_stats_grid.dart          # Grille de statistiques
│       ├── dashboard_stats_card.dart          # Carte de statistique individuelle
│       ├── dashboard_quick_actions_grid.dart  # Grille d'actions rapides
│       ├── dashboard_quick_action_button.dart # Bouton d'action individuel
│       ├── dashboard_recent_activity_section.dart # Section d'activité récente
│       ├── dashboard_activity_tile.dart       # Tuile d'activité individuelle
│       ├── dashboard_insights_section.dart    # Section d'insights/métriques
│       ├── dashboard_metric_row.dart          # Ligne de métrique avec progression
│       └── dashboard_drawer.dart              # Menu latéral de navigation
└── README.md                                  # Cette documentation

🏗️ Architecture

Principe de Séparation

Chaque widget est dans son propre fichier pour garantir :

• Maintenabilité : Modifications isolées sans impact sur les autres composants
• Réutilisabilité : Widgets réutilisables dans d'autres contextes
• Testabilité : Tests unitaires focalisés sur chaque composant
• Lisibilité : Code organisé et facile à comprendre

Hiérarchie des Widgets

🔝 Niveau Page

• DashboardPageStable : Page principale qui orchestre tous les widgets

🏢 Niveau Section

• DashboardWelcomeSection : Message d'accueil avec gradient
• DashboardStatsGrid : Grille 2x2 des statistiques principales
• DashboardQuickActionsGrid : Grille 2x2 des actions rapides
• DashboardRecentActivitySection : Liste des activités récentes
• DashboardInsightsSection : Métriques de performance
• DashboardDrawer : Menu latéral de navigation

⚛️ Niveau Atomique

• DashboardStatsCard : Carte individuelle de statistique
• DashboardQuickActionButton : Bouton d'action individuel
• DashboardActivityTile : Tuile d'activité individuelle
• DashboardMetricRow : Ligne de métrique avec barre de progression

📊 Modèles de Données

DashboardStat

class DashboardStat {
  final IconData icon;
  final String value;
  final String title;
  final Color color;
  final VoidCallback? onTap;
}

DashboardQuickAction

class DashboardQuickAction {
  final IconData icon;
  final String title;
  final Color color;
  final VoidCallback? onTap;
}

DashboardActivity

class DashboardActivity {
  final String title;
  final String subtitle;
  final IconData icon;
  final Color color;
  final String time;
  final VoidCallback? onTap;
}

DashboardMetric

class DashboardMetric {
  final String label;
  final String value;
  final double progress;
  final Color color;
  final VoidCallback? onTap;
}

DrawerMenuItem

class DrawerMenuItem {
  final IconData icon;
  final String title;
  final VoidCallback? onTap;
}

🎨 Design System

Tous les widgets utilisent les tokens du design system :

• ColorTokens : Palette de couleurs cohérente
• TypographyTokens : Système typographique hiérarchisé
• SpacingTokens : Espacement basé sur une grille 4px

🔄 Callbacks et Navigation

Chaque widget expose des callbacks pour les interactions :

• onStatTap(String statType) : Action sur une statistique
• onActionTap(String actionType) : Action rapide
• onActivityTap(String activityId) : Détail d'une activité
• onMetricTap(String metricType) : Détail d'une métrique
• onNavigate(String route) : Navigation depuis le drawer
• onLogout() : Déconnexion

📱 Responsive Design

Tous les widgets sont conçus pour être responsifs :

• Grilles avec childAspectRatio optimisé
• Padding et spacing adaptatifs
• Typographie scalable
• Icônes avec tailles cohérentes

🧪 Tests

Structure recommandée pour les tests :

test/
├── features/
│   └── dashboard/
│       └── presentation/
│           └── widgets/
│               ├── dashboard_welcome_section_test.dart
│               ├── dashboard_stats_card_test.dart
│               ├── dashboard_quick_action_button_test.dart
│               └── ...

🚀 Utilisation

Import Simple

import '../widgets/widgets.dart'; // Importe tous les widgets

Utilisation dans une Page

class MyDashboard extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: Column(
        children: [
          DashboardWelcomeSection(),
          DashboardStatsGrid(onStatTap: _handleStatTap),
          DashboardQuickActionsGrid(onActionTap: _handleAction),
          // ...
        ],
      ),
    );
  }
}

🔧 Maintenance

Ajout d'un Nouveau Widget

1. Créer le fichier dans widgets/
2. Implémenter le widget avec sa documentation
3. Ajouter l'export dans widgets.dart
4. Créer les tests correspondants
5. Mettre à jour cette documentation

Modification d'un Widget Existant

1. Modifier uniquement le fichier concerné
2. Vérifier que les interfaces (callbacks) restent compatibles
3. Mettre à jour les tests si nécessaire
4. Tester l'impact sur les widgets parents

Cette architecture garantit une maintenabilité optimale et une évolutivité maximale du module dashboard.