unionflow-server-api/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
```dart
class DashboardStat {
  final IconData icon;
  final String value;
  final String title;
  final Color color;
  final VoidCallback? onTap;
}
```

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

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

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

### DrawerMenuItem
```dart
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
```dart
import '../widgets/widgets.dart'; // Importe tous les widgets
```

### Utilisation dans une Page
```dart
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.