btpxpress-frontend/DASHBOARD_CONCEPTION.md

# Conception Dashboard BTP Xpress - 100% Données Réelles API

**Date**: 2025-11-01
**Objectif**: Dashboard professionnel couvrant TOUS les aspects métiers BTP Xpress
**Principe**: AUCUNE donnée fictive - 100% données réelles de l'API backend

---

## Architecture de disposition

### Layout global: 3 colonnes responsives

```
┌─────────────────────────────────────────────────────────────────┐
│                   BARRE D'ALERTES (conditionnelle)               │
└─────────────────────────────────────────────────────────────────┘
┌────────────────────────┬────────────────────────┬────────────────┐
│    KPI Principal 1     │    KPI Principal 2     │   KPI Principal 3 │
│   (Chantiers actifs)   │    (Équipes dispo)     │  (Maintenance)    │
└────────────────────────┴────────────────────────┴────────────────┘
┌─────────────────────────────────────┬──────────────────────────────┐
│                                     │                              │
│   GRAPHIQUE D'ACTIVITÉ              │   KPIs RESSOURCES            │
│   (Chantiers par statut)            │   - Employés actifs          │
│                                     │   - Matériel disponible      │
│                                     │   - Taux d'utilisation       │
│                                     │                              │
└─────────────────────────────────────┴──────────────────────────────┘
┌──────────────────────────────────────────────────────────────────┐
│                                                                  │
│   TABLEAU CHANTIERS ACTIFS                                       │
│   (nom, client, budget, avancement, statut)                      │
│                                                                  │
└──────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────┬──────────────────────────────┐
│                                     │                              │
│   CHANTIERS EN RETARD               │   MAINTENANCES EN RETARD     │
│   (timeline avec détails)           │   (liste avec matériel)      │
│                                     │                              │
└─────────────────────────────────────┴──────────────────────────────┘
┌─────────────────────────────────────┬──────────────────────────────┐
│                                     │                              │
│   DISPONIBILITÉS EN ATTENTE         │   ÉVÉNEMENTS AUJOURD'HUI     │
│   (demandes congés/absences)        │   (planning du jour)         │
│                                     │                              │
└─────────────────────────────────────┴──────────────────────────────┘
┌──────────────────────────────────────────────────────────────────┐
│                                                                  │
│   DOCUMENTS RÉCENTS                                              │
│   (5 derniers documents ajoutés)                                 │
│                                                                  │
└──────────────────────────────────────────────────────────────────┘
```

---

## Mapping des données API vers composants UI

### 1. Barre d'alertes (affichée si totalAlertes > 0)

**API**: `GET /api/v1/dashboard/alertes`

```json
{
  "totalAlertes": 12,
  "alerteCritique": true,
  "maintenance": { "enRetard": 3, "details": [...] },
  "chantiers": { "enRetard": 5, "details": [...] },
  "disponibilites": { "enAttente": 2, "details": [...] },
  "planning": { "conflits": 2, "details": [...] }
}
```

**UI**: Bannière rouge en haut avec icône ⚠️
- "**12 alertes** nécessitent votre attention" + bouton "Voir les détails"

---

### 2. KPIs Principaux (3 cartes en ligne)

#### KPI 1: Chantiers Actifs
**API**: `GET /api/v1/dashboard` → `chantiers`

```json
"chantiers": {
  "total": 45,
  "actifs": 28,
  "tauxActivite": 62.22
}
```

**UI**: Carte blanche avec icône 🏗️
- **Titre**: "Chantiers actifs"
- **Nombre**: `28` (grand, bold)
- **Sous-titre**: "Sur 45 au total"
- **Badge**: `62.22%` d'activité

#### KPI 2: Équipes Disponibles
**API**: `GET /api/v1/dashboard` → `equipes`

```json
"equipes": {
  "total": 12,
  "disponibles": 5,
  "tauxDisponibilite": 41.67
}
```

**UI**: Carte bleue avec icône 👥
- **Titre**: "Équipes disponibles"
- **Nombre**: `5/12`
- **ProgressBar**: 41.67%
- **Sous-titre**: "Taux de disponibilité"

#### KPI 3: Maintenances Critiques
**API**: `GET /api/v1/dashboard` → `maintenance`

```json
"maintenance": {
  "enRetard": 3,
  "planifiees": 8,
  "alerteRetard": true
}
```

**UI**: Carte rouge (si alerteRetard) ou verte avec icône 🔧
- **Titre**: "Maintenances en retard"
- **Nombre**: `3` (rouge si > 0)
- **Sous-titre**: "8 planifiées"
- **Badge**: "URGENT" si enRetard > 0

---

### 3. Graphique d'activité (Chart.js)

**API**: `GET /api/v1/dashboard/chantiers` → `statistiques`

**Type**: Doughnut Chart (camembert)
- **EN_COURS**: nombre + pourcentage
- **PLANIFIE**: nombre + pourcentage
- **TERMINE**: nombre + pourcentage
- **SUSPENDU**: nombre + pourcentage
- **ANNULE**: nombre + pourcentage

**Couleurs Freya**:
- EN_COURS: `--primary-color` (violet)
- PLANIFIE: `--blue-500`
- TERMINE: `--green-500`
- SUSPENDU: `--orange-500`
- ANNULE: `--red-500`

---

### 4. KPIs Ressources (colonne droite)

**API**: `GET /api/v1/dashboard/ressources`

```json
{
  "equipes": { "total": 12, "disponibles": 5, "tauxDisponibilite": 41.67 },
  "employes": { "total": 156, "actifs": 142, "tauxActivite": 91.03 },
  "materiel": { "total": 89, "disponible": 67, "tauxDisponibilite": 75.28 }
}
```

**UI**: 3 sous-cartes empilées

#### 4.1 Employés Actifs
- **Icon**: 👨‍💼
- **Nombre**: `142/156`
- **Label**: "Employés actifs"
- **ProgressBar**: 91.03% (vert si > 80%, orange si > 60%, rouge sinon)

#### 4.2 Matériel Disponible
- **Icon**: 🚜
- **Nombre**: `67/89`
- **Label**: "Matériel disponible"
- **ProgressBar**: 75.28%

#### 4.3 Taux d'utilisation global
- **Calcul frontend**: moyenne des 3 taux (chantiers, équipes, employés)
- **ProgressBar circulaire**: donut chart mini

---

### 5. Tableau Chantiers Actifs

**API**: `GET /api/v1/dashboard/chantiers` → `chantiersActifs` (array)

```json
"chantiersActifs": [
  {
    "id": "uuid",
    "nom": "Rénovation Villa Dauphine",
    "client": "Jean Dupont",
    "dateDebut": "2025-01-15",
    "dateFinPrevue": "2025-04-30",
    "statut": "EN_COURS",
    "budget": 250000.00,
    "coutReel": 180000.00,
    "avancement": 72
  }
]
```

**UI**: PrimeFaces DataTable responsive

| Nom | Client | Début | Fin prévue | Avancement | Budget | Coût réel | Statut | Actions |
|-----|--------|-------|------------|------------|--------|-----------|--------|---------|
| Rénovation Villa Dauphine | Jean Dupont | 15/01/2025 | 30/04/2025 | ██████░░ 72% | 250 000 Fcfa | 180 000 Fcfa | 🟢 EN_COURS | 👁️ |

**Colonnes**:
1. **Nom**: Texte (lien vers détails)
2. **Client**: Texte
3. **Date Début**: Format `dd/MM/yyyy`
4. **Date Fin Prévue**: Format `dd/MM/yyyy`
5. **Avancement**: ProgressBar avec %
6. **Budget**: Formaté avec `fcfaConverter`
7. **Coût Réel**: Formaté avec `fcfaConverter` + Badge (vert si < budget, rouge sinon)
8. **Statut**: Badge coloré selon statut
9. **Actions**: Bouton "Voir détails"

**Pagination**: 10 par page
**Tri**: Par date de début (décroissant)

---

### 6. Chantiers en Retard (Timeline)

**API**: `GET /api/v1/dashboard/chantiers` → `chantiersEnRetard` (array)

```json
"chantiersEnRetard": [
  {
    "id": "uuid",
    "nom": "Construction Immeuble B",
    "dateFinPrevue": "2025-10-15",
    "joursRetard": 17
  }
]
```

**UI**: Timeline Freya (ul.timeline)

```html
<li class="red">
    <i class="pi pi-circle-on"></i>
    <div class="event-content">
        <span class="event-title">Construction Immeuble B</span>
        <span>Date prévue : 15/10/2025</span>
        <span class="time">+17 jours de retard</span>
    </div>
</li>
```

**Affichage**: Max 5 chantiers les plus en retard
**Message si vide**: "✅ Tous les chantiers sont dans les temps"

---

### 7. Maintenances en Retard

**API**: `GET /api/v1/dashboard/maintenance` → `maintenancesEnRetard` (array)

```json
"maintenancesEnRetard": [
  {
    "id": "uuid",
    "materiel": "Pelleteuse CAT 320",
    "type": "PREVENTIVE",
    "datePrevue": "2025-10-20",
    "description": "Vidange et filtres",
    "joursRetard": 12
  }
]
```

**UI**: Liste avec badges

```html
<div class="maintenance-item urgente">
    <h6>🔧 Pelleteuse CAT 320</h6>
    <p>Type: PREVENTIVE • Prévue: 20/10/2025</p>
    <p class="description">Vidange et filtres</p>
    <p:badge value="+12 jours" severity="danger"/>
</div>
```

**Tri**: Par nombre de jours de retard (décroissant)
**Limite**: 5 maintenances maximum

---

### 8. Disponibilités en Attente

**API**: `GET /api/v1/dashboard/ressources` → `disponibilites.enAttenteDetails` (array)

```json
"disponibilites": {
  "enAttenteDetails": [
    {
      "id": "uuid",
      "employe": "Pierre Martin",
      "type": "CONGE",
      "dateDebut": "2025-11-15T00:00:00",
      "dateFin": "2025-11-22T23:59:59",
      "motif": "Congés annuels"
    }
  ]
}
```

**UI**: Liste avec cartes

```html
<div class="disponibilite-card">
    <div class="employee-name">
        <i class="pi pi-user"></i>
        Pierre Martin
    </div>
    <div class="dispo-details">
        <p:badge value="CONGE" severity="info"/>
        <span>Du 15/11 au 22/11 (7 jours)</span>
        <small>Motif: Congés annuels</small>
    </div>
    <div class="actions">
        <p:button icon="pi pi-check" label="Approuver" class="ui-button-success ui-button-sm"/>
        <p:button icon="pi pi-times" label="Refuser" class="ui-button-danger ui-button-sm"/>
    </div>
</div>
```

**Affichage**: Toutes les disponibilités en attente
**Badge**: Couleur selon type (CONGE=bleu, MALADIE=orange, FORMATION=vert)

---

### 9. Événements Aujourd'hui

**API**: `GET /api/v1/dashboard` → `planning.evenementsAujourdhui`

**Données**:
```json
"planning": {
  "evenementsAujourdhui": 8
}
```

**API détaillée**: `GET /api/v1/dashboard/planning` (si besoin de détails)

**UI**: Carte avec compteur

```html
<div class="events-today-card">
    <i class="pi pi-calendar" style="font-size: 3rem; color: var(--primary-color)"></i>
    <h2>8</h2>
    <h6>Événements aujourd'hui</h6>
    <p:button label="Voir le planning" icon="pi pi-arrow-right" class="ui-button-text"/>
</div>
```

---

### 10. Documents Récents

**API**: `GET /api/v1/dashboard` → `documents.recents` (array)

```json
"documents": {
  "total": 2456,
  "recents": [
    {
      "id": "uuid",
      "nom": "Devis Villa Dauphine.pdf",
      "type": "DEVIS",
      "dateCreation": "2025-11-01T14:23:00"
    }
  ]
}
```

**UI**: Liste avec icônes de type de document

```html
<ul class="documents-list">
    <li>
        <i class="pi pi-file-pdf"></i>
        <div class="doc-info">
            <span class="doc-name">Devis Villa Dauphine.pdf</span>
            <small>DEVIS • Ajouté le 01/11/2025 à 14:23</small>
        </div>
        <p:button icon="pi pi-download" class="ui-button-text ui-button-sm"/>
    </li>
</ul>
```

**Icônes selon type**:
- DEVIS: `pi-file-pdf`
- FACTURE: `pi-dollar`
- CONTRAT: `pi-file-edit`
- PLAN: `pi-image`
- AUTRE: `pi-file`

**Limite**: 5 documents récents

---

## Endpoints API utilisés (complet)

| Endpoint | Méthode | Usage | Fréquence |
|----------|---------|-------|-----------|
| `/api/v1/dashboard` | GET | KPIs principaux, vue globale | Init |
| `/api/v1/dashboard/chantiers` | GET | Chantiers actifs, en retard, stats | Init |
| `/api/v1/dashboard/ressources` | GET | Équipes, employés, matériel, disponibilités | Init |
| `/api/v1/dashboard/maintenance` | GET | Maintenances en retard et planifiées | Init |
| `/api/v1/dashboard/alertes` | GET | Toutes les alertes critiques | Init + polling 30s |
| `/api/v1/dashboard/planning` | GET | Événements du jour, conflits | Optionnel |

---

## Détails techniques

### Palette de couleurs Freya

```css
/* KPI Cards */
.card.overview-box.white { background: #FFFFFF; color: var(--text-color); }
.card.overview-box.blue { background: var(--blue-500); color: white; }
.card.overview-box.green { background: var(--green-500); color: white; }
.card.overview-box.orange { background: var(--orange-500); color: white; }
.card.overview-box.red { background: var(--red-500); color: white; }

/* Statuts chantiers */
.badge-en-cours { background: var(--primary-color); } /* Violet */
.badge-planifie { background: var(--blue-500); }
.badge-termine { background: var(--green-500); }
.badge-suspendu { background: var(--orange-500); }
.badge-annule { background: var(--red-500); }
```

### Responsive breakpoints

```scss
// Freya breakpoints
$mobile: 768px;
$tablet: 992px;
$desktop: 1200px;

// Grid responsive
col-12                  // 100% sur tous écrans
md:col-6                // 50% à partir de tablet
xl:col-4                // 33% à partir de desktop
xl:col-8                // 66% à partir de desktop
```

### Formatage des nombres

```java
// Converter FCFA
@FacesConverter("fcfaConverter")
public class FcfaConverter implements Converter<Double> {
    @Override
    public String getAsString(FacesContext ctx, UIComponent comp, Double value) {
        if (value == null) return "0";
        DecimalFormat df = new DecimalFormat("#,##0");
        return df.format(value);
    }
}

// Usage XHTML
<h:outputText value="#{chantier.budget}">
    <f:converter converterId="fcfaConverter"/>
</h:outputText>
<h:outputText value=" Fcfa"/>
```

### Formatage des dates

```java
// Pattern français
private static final DateTimeFormatter DATE_FORMATTER =
    DateTimeFormatter.ofPattern("dd/MM/yyyy");

private static final DateTimeFormatter DATETIME_FORMATTER =
    DateTimeFormatter.ofPattern("dd/MM/yyyy HH:mm");

// Méthodes dans DashboardView
public String formatDate(LocalDate date) {
    return date != null ? date.format(DATE_FORMATTER) : "";
}

public String formatDateTime(LocalDateTime dateTime) {
    return dateTime != null ? dateTime.format(DATETIME_FORMATTER) : "";
}
```

---

## Gestion des états vides

Chaque section doit afficher un message approprié si aucune donnée :

| Section | Message si vide |
|---------|-----------------|
| Chantiers actifs | "Aucun chantier actif pour le moment" |
| Chantiers en retard | "✅ Tous les chantiers sont dans les temps" |
| Maintenances en retard | "✅ Toutes les maintenances sont à jour" |
| Disponibilités en attente | "Aucune demande de disponibilité en attente" |
| Documents récents | "Aucun document récent" |
| Alertes | Barre d'alertes masquée si totalAlertes === 0 |

---

## Refresh et temps réel

### Stratégie de rafraîchissement

1. **Chargement initial** (@PostConstruct): Tous les endpoints
2. **Bouton "Rafraîchir"**: Recharge toutes les données
3. **Polling automatique** (optionnel):
   - Alertes: toutes les 30 secondes
   - Chantiers/ressources: toutes les 5 minutes

### Implémentation polling (PrimeFaces Poll)

```xhtml
<!-- Poll automatique des alertes -->
<p:poll interval="30" listener="#{dashboardView.refreshAlertes}"
        update="alertes-panel" autoStart="true"/>

<!-- Poll optionnel (désactivé par défaut) -->
<p:poll interval="300" listener="#{dashboardView.rafraichir}"
        update="@form" autoStart="false" widgetVar="dashboardPoll"/>

<!-- Bouton manuel -->
<p:commandButton value="Rafraîchir" icon="pi pi-refresh"
                 action="#{dashboardView.rafraichir}"
                 update="@form" styleClass="ui-button-text"/>
```

---

## Aspects métiers couverts

✅ **Chantiers**: Vue globale, actifs, en retard, budget, avancement
✅ **Ressources Humaines**: Employés actifs, équipes, disponibilités
✅ **Matériel**: Disponibilité, maintenance, alertes
✅ **Planning**: Événements du jour, conflits
✅ **Finances**: Budget vs coût réel par chantier
✅ **Maintenance**: En retard, planifiées, alertes critiques
✅ **Documents**: Récents, accès rapide
✅ **Alertes**: Vue consolidée de tout ce qui nécessite attention

---

## Points d'attention

🚫 **Aucune donnée fictive/mockée**
✅ **Toutes les données proviennent strictement de l'API**
✅ **Gestion d'erreur robuste** (null checks, try-catch)
✅ **Messages appropriés** pour les états vides
✅ **Performance**: Chargement asynchrone si nécessaire
✅ **Logging**: Toutes les opérations API sont loguées
✅ **JavaDoc**: Documentation française complète

---

**Prochaine étape**: Implémentation du dashboard.xhtml avec cette conception