unionflow-server-api/unionflow/docs/KPI_DASHBOARD_PAR_ROLE.md

# KPI Dashboard - Matrice Métier par Rôle

> Date: 2026-03-02
> Système: UnionFlow - Dashboards Personnalisés

## Principe de Conception

Chaque rôle voit **uniquement les KPI pertinents** pour ses responsabilités :
- **Membres** → Données **personnelles** (mes cotisations, mon épargne)
- **Responsables** → Données **de leur domaine** (finances, événements, aides)
- **Admins** → Données **globales** (toute l'organisation)

---

## 1. MEMBRE_ACTIF - Dashboard Personnel

**Page** : `/pages/secure/dashboard-membre.xhtml`
**Principe** : **MES données** (pas de statistiques globales)

### KPI Affichés

| KPI | Valeur Affichée | Métrique Secondaire | Pertinence Métier |
|-----|----------------|---------------------|-------------------|
| **Mes Cotisations** | Statut (À jour/En retard) | Montant payé ce mois | ✅ Le membre doit savoir s'il est à jour |
| **Mon Épargne** | Solde total en FCFA | Évolution ce mois (+/- FCFA) | ✅ Le membre suit son épargne personnelle |
| **Mes Événements** | Nombre d'inscriptions | Événements à venir | ✅ Le membre voit ses participations |
| **Mes Aides** | Nombre de demandes | Demandes en traitement | ✅ Le membre suit ses demandes d'aide |

### Messages par Défaut (Données Vides)

| KPI | Message si Vide | Couleur |
|-----|-----------------|---------|
| Cotisations | "Aucune cotisation enregistrée" | Neutre (text-500) |
| Épargne | "Aucune épargne enregistrée" | Neutre (text-500) |
| Événements | "Aucune inscription" | Neutre (text-500) |
| Aides | "Aucune demande" | Neutre (text-500) |

### ❌ Ce qui NE DOIT PAS apparaître

- ❌ Nombre total de membres de l'organisation
- ❌ Cotisations collectées globales
- ❌ Trésorerie totale
- ❌ Statistiques d'événements globales
- ❌ Demandes d'aide des autres membres
- ❌ "Aucun utilisateur actif" (message admin non pertinent)

---

## 2. TRESORIER - Dashboard Financier

**Page** : `/pages/secure/dashboard.xhtml` (avec composants filtrés)
**Principe** : Vision **financière globale** de l'organisation

### KPI Affichés

| KPI | Valeur Affichée | Métrique Secondaire | Pertinence Métier |
|-----|----------------|---------------------|-------------------|
| **FCFA Collectés** | Total cotisations collectées | Évolution vs mois dernier | ✅ Suivi de la trésorerie entrante |
| **Trésorerie** | Solde en caisse | Évolution mensuelle | ✅ Santé financière globale |
| **Impayés** | Montant en retard | Nombre de membres concernés | ✅ Recouvrement à effectuer |
| **Dépenses** | Total dépenses du mois | Comparaison au budget | ✅ Contrôle budgétaire |

### Actions Rapides

- ✅ Collecter (enregistrer paiement)
- ✅ Rapport financier
- ✅ Relancer cotisations en retard

### ❌ Ce qui NE DOIT PAS apparaître

- ❌ Données événementielles (pas son domaine)
- ❌ Gestion administrative des membres (domaine SECRETAIRE)

---

## 3. SECRETAIRE - Dashboard Administratif

**Page** : `/pages/secure/dashboard.xhtml` (avec composants filtrés)
**Principe** : Gestion **administrative** et suivi des **membres**

### KPI Affichés

| KPI | Valeur Affichée | Métrique Secondaire | Pertinence Métier |
|-----|----------------|---------------------|-------------------|
| **Membres Actifs** | Nombre total | Évolution ce mois | ✅ Suivi de la croissance |
| **Adhésions Pendantes** | Demandes en attente | À valider | ✅ Tâche prioritaire |
| **Taux d'Activité** | Pourcentage membres actifs | Comparaison objectif | ✅ Vitalité de l'organisation |
| **Cartes à Renouveler** | Nombre | Dans les 30 jours | ✅ Gestion administrative |

### Actions Rapides

- ✅ Nouveau membre (inscription)
- ✅ Valider adhésions
- ✅ Rapport membres

### ❌ Ce qui NE DOIT PAS apparaître

- ❌ Détails financiers (montants, trésorerie) - domaine TRESORIER
- ❌ Gestion des aides sociales - domaine RESPONSABLE_SOCIAL

---

## 4. RESPONSABLE_SOCIAL - Dashboard Aides Sociales

**Page** : `/pages/secure/dashboard.xhtml` (avec composants filtrés)
**Principe** : Suivi des **aides sociales** et **solidarité**

### KPI Affichés

| KPI | Valeur Affichée | Métrique Secondaire | Pertinence Métier |
|-----|----------------|---------------------|-------------------|
| **FCFA Distribués** | Total aides versées | Évolution mensuelle | ✅ Impact social de l'organisation |
| **Demandes en Attente** | Nombre à traiter | Ancienneté moyenne | ✅ Tâche prioritaire |
| **Bénéficiaires** | Nombre de membres aidés | Ce mois | ✅ Portée de l'action sociale |
| **Budget Social** | Montant restant | Pourcentage utilisé | ✅ Capacité d'aide restante |

### Actions Rapides

- ✅ Traiter demandes
- ✅ Évaluation sociale
- ✅ Rapport aides

### ❌ Ce qui NE DOIT PAS apparaître

- ❌ Détails événementiels
- ❌ Gestion administrative des membres

---

## 5. RESPONSABLE_EVENEMENTS - Dashboard Événementiel

**Page** : `/pages/secure/dashboard.xhtml` (avec composants filtrés)
**Principe** : Organisation et suivi des **événements**

### KPI Affichés

| KPI | Valeur Affichée | Métrique Secondaire | Pertinence Métier |
|-----|----------------|---------------------|-------------------|
| **Taux de Participation** | Pourcentage moyen | Comparaison objectif | ✅ Engagement des membres |
| **Événements Prévus** | Nombre à venir | Dans les 30 jours | ✅ Planification |
| **Inscriptions** | Total en attente | À confirmer | ✅ Logistique à prévoir |
| **Événements à Planifier** | Nombre | Action requise | ✅ Tâche prioritaire |

### Actions Rapides

- ✅ Nouvel événement
- ✅ Planification
- ✅ Gestion participants

### ❌ Ce qui NE DOIT PAS apparaître

- ❌ Montants financiers détaillés (sauf budget événement)
- ❌ Gestion des membres (sauf participants événements)

---

## 6. ADMIN_ORGANISATION - Dashboard Global

**Page** : `/pages/secure/dashboard.xhtml` (tous composants visibles)
**Principe** : **Vue d'ensemble** complète de l'organisation

### KPI Affichés (Tous)

✅ **Membres** : Membres actifs, adhésions, taux d'activité
✅ **Finances** : Cotisations, trésorerie, impayés, dépenses
✅ **Aides** : Aides distribuées, demandes en attente, bénéficiaires
✅ **Événements** : Taux de participation, événements prévus, inscriptions

### Actions Rapides (Toutes)

- ✅ Nouveau membre
- ✅ Collecter
- ✅ Événement
- ✅ Rapport

---

## 7. SUPER_ADMIN - Dashboard Multi-Organisations

**Page** : `/pages/super-admin/dashboard.xhtml`
**Principe** : Gestion **multi-tenant**, vue sur **toutes les organisations**

### KPI Affichés

| KPI | Valeur Affichée | Métrique Secondaire | Pertinence Métier |
|-----|----------------|---------------------|-------------------|
| **Organisations Actives** | Nombre total | Nouvelles ce mois | ✅ Croissance plateforme |
| **Membres Total** | Tous membres | Répartition par organisation | ✅ Adoption plateforme |
| **Chiffre d'Affaires** | Total cotisations | Par organisation | ✅ Performance globale |
| **Incidents** | Nombre ouvert | Criticité | ✅ Santé système |

---

## Règles de Conception UX

### 1. Pertinence Métier

**Principe** : Chaque KPI doit répondre à la question "Qu'est-ce que je dois savoir pour faire mon travail ?"

✅ **BON** : TRESORIER voit "Impayés : 45,000 FCFA"
❌ **MAUVAIS** : MEMBRE_ACTIF voit "Impayés : 45,000 FCFA" (pas son rôle de gérer ça)

### 2. Messages par Défaut

**Éviter les messages génériques non contextuels** :

❌ **MAUVAIS** : "Aucun utilisateur actif" dans un dashboard personnel
✅ **BON** : "Aucune cotisation enregistrée" (contextuel)

❌ **MAUVAIS** : "Données non disponibles" (vague)
✅ **BON** : "Aucune inscription" (spécifique)

### 3. Granularité des Données

**Niveau de détail selon le rôle** :

| Rôle | Niveau de Détail |
|------|-----------------|
| MEMBRE_ACTIF | **Individuel** (mes données uniquement) |
| RESPONSABLE | **Domaine** (finances OU événements OU aides) |
| ADMIN | **Global** (toute l'organisation) |
| SUPER_ADMIN | **Multi-tenant** (toutes organisations) |

### 4. Couleurs Sémantiques

| Statut | Couleur | Usage |
|--------|---------|-------|
| Positif | `green-600` | À jour, objectif atteint |
| Attention | `orange-600` | En retard, action requise |
| Critique | `red-600` | Bloquant, urgent |
| Neutre | `blue-600` | Informatif |
| Secondaire | `gray-500` | Données vides, pas d'alerte |

---

## Checklist de Validation

Avant d'afficher un KPI, vérifier :

- [ ] **Pertinence** : Le rôle a-t-il besoin de cette info pour son travail ?
- [ ] **Actionnabilité** : Le KPI mène-t-il à une action concrète ?
- [ ] **Granularité** : Niveau de détail adapté au rôle ?
- [ ] **Message vide** : Message par défaut contextuel et pertinent ?
- [ ] **Cohérence** : Unité cohérente (FCFA, nombre, %) ?

---

## Exemples de Corrections

### ❌ Avant (Problème)

```xml
<!-- Dashboard MEMBRE_ACTIF -->
<ui:param name="title" value="Trésorerie Globale" />
<ui:param name="value" value="1,500,000 FCFA" />
<ui:param name="statusValue" value="#{bean.utilisateursActifs}" />
<!-- Message: "Aucun utilisateur actif" si vide -->
```

**Problèmes** :
1. Trésorerie globale ≠ donnée personnelle membre
2. "Aucun utilisateur actif" n'a aucun sens pour un membre

### ✅ Après (Corrigé)

```xml
<!-- Dashboard MEMBRE_ACTIF -->
<ui:param name="title" value="Mes Cotisations" />
<ui:param name="value" value="À jour" />
<ui:param name="growthValue" value="25000" />
<ui:param name="growthLabel" value="FCFA payés ce mois" />
<ui:param name="noDataLabel" value="Aucune cotisation enregistrée" />
```

**Améliorations** :
1. ✅ Donnée personnelle (MES cotisations)
2. ✅ Message contextuel et pertinent
3. ✅ Actionnable (payer si en retard)

---

## Maintenance

**Révision** : Trimestrielle ou à chaque ajout de rôle
**Responsable** : Product Owner + Équipe UX
**Tests** : Validation avec utilisateurs finaux de chaque rôle

---

## Contact

**Documentation** : `docs/KPI_DASHBOARD_PAR_ROLE.md`
**Code** : `/pages/secure/dashboard.xhtml`, `/pages/secure/dashboard-membre.xhtml`
**Composant** : `/templates/components/cards/kpi-card.xhtml`