serv_benchmark/docs/FEATURE_VERSION_DISPLAY.md

# Affichage des versions Frontend et Backend

## Date
2026-01-10

## Contexte

Pour faciliter le débogage et la vérification que les bonnes versions sont chargées (surtout après des mises à jour), un affichage des versions a été ajouté dans le header de toutes les pages principales.

## Fonctionnalité

### Affichage dans le header

Les versions Frontend et Backend sont affichées en haut à droite du header:

```
Frontend: v2.1.0
Backend: v2.1.0
```

- **Position**: Coin supérieur droit du header
- **Format**: Petit texte grisé (discret mais visible)
- **Tooltip**: Affiche la date de build au survol
- **Pages concernées**:
  - `device_detail.html`
  - `devices.html`

### Informations affichées

#### Frontend
- **Version**: Numéro de version sémantique (ex: 2.1.0)
- **Build date**: Date de compilation
- **Features**: Liste des fonctionnalités principales

#### Backend
- **Version**: Numéro de version sémantique (ex: 2.1.0)
- **Build date**: Date de compilation
- **Python version**: Version Python requise
- **Features**: Liste des fonctionnalités principales

## Implémentation

### 1. Frontend - Fichier version

**Fichier**: `frontend/version.json`

```json
{
  "version": "2.1.0",
  "build_date": "2026-01-10",
  "features": [
    "Affichage compact des slots mémoire",
    "Bouton rafraîchissement forcé",
    "Import PCI avec pré-remplissage",
    "Champ utilisation avec hosts",
    "Détection Proxmox"
  ]
}
```

**Accès**: `http://localhost:8087/version.json`

### 2. Backend - Endpoint /version

**Fichier**: `backend/app/api/benchmark.py` (lignes 34-50)

```python
@router.get("/version")
async def get_version():
    """
    Get backend version information.
    """
    return {
        "version": "2.1.0",
        "build_date": "2026-01-10",
        "python_version": "3.11+",
        "features": [
            "Détection Proxmox",
            "Migration RAM slots avec form_factor",
            "Endpoint /config/hosts",
            "Support PCI device import",
            "Champ utilisation périphériques"
        ]
    }
```

**Accès**: `http://localhost:8007/api/version`

### 3. HTML - Affichage dans le header

**Fichier**: `frontend/device_detail.html` (lignes 17-26)

```html
<div style="display: flex; justify-content: space-between; align-items: center;">
  <div>
    <h1>🚀 Linux BenchTools</h1>
    <p>Détail du device</p>
  </div>
  <div id="version-info" style="font-size: 0.75rem; color: var(--text-muted); text-align: right;">
    <div>Frontend: <span id="frontend-version">...</span></div>
    <div>Backend: <span id="backend-version">...</span></div>
  </div>
</div>
```

**Fichier**: `frontend/devices.html` (lignes 23-26)

```html
<div id="version-info" style="font-size: 0.7rem; color: var(--text-muted); text-align: right;">
  <div>Frontend: <span id="frontend-version">...</span></div>
  <div>Backend: <span id="backend-version">...</span></div>
</div>
```

### 4. JavaScript - Chargement des versions

**Fichier**: `frontend/js/device_detail.js` (lignes 22-42)

```javascript
// Load version information
async function loadVersionInfo() {
  try {
    // Load frontend version
    const frontendResp = await fetch('version.json');
    const frontendVersion = await frontendResp.json();
    document.getElementById('frontend-version').textContent = `v${frontendVersion.version}`;
    document.getElementById('frontend-version').title = `Build: ${frontendVersion.build_date}`;

    // Load backend version
    const apiUrl = window.BenchConfig?.backendApiUrl || 'http://localhost:8007/api';
    const backendResp = await fetch(`${apiUrl}/version`);
    const backendVersion = await backendResp.json();
    document.getElementById('backend-version').textContent = `v${backendVersion.version}`;
    document.getElementById('backend-version').title = `Build: ${backendVersion.build_date}`;
  } catch (error) {
    console.error('Failed to load version info:', error);
    document.getElementById('frontend-version').textContent = 'N/A';
    document.getElementById('backend-version').textContent = 'N/A';
  }
}
```

**Appel au chargement** (ligne 47):
```javascript
document.addEventListener('DOMContentLoaded', async () => {
  // Load version info
  loadVersionInfo();
  // ... rest of initialization
});
```

## Cas d'usage

### 1. Vérification après mise à jour

Après avoir mis à jour le code:
1. Recharger la page (bouton 🔄 ou Ctrl+F5)
2. Vérifier que les versions affichées correspondent aux versions attendues
3. Si les versions ne correspondent pas → problème de cache

**Exemple**:
- Attendu: v2.1.0
- Affiché: v2.0.5
- → Cache navigateur ou container Docker pas à jour

### 2. Débogage de problèmes

Si un utilisateur signale un bug:
1. Demander les versions affichées
2. Comparer avec les versions déployées
3. Identifier si le problème vient du frontend ou backend

### 3. Compatibilité Frontend/Backend

Vérifier que les versions sont compatibles:
- Frontend v2.1.0 + Backend v2.1.0 ✅
- Frontend v2.1.0 + Backend v2.0.0 ⚠️ (peut causer des problèmes)

### 4. Suivi des déploiements

En production, vérifier rapidement quelle version est déployée:
- Ouvrir la page
- Regarder le coin supérieur droit
- Versions visibles immédiatement

## Versioning sémantique

Format: **MAJOR.MINOR.PATCH** (ex: 2.1.0)

- **MAJOR** (2): Changements incompatibles avec l'API
- **MINOR** (1): Nouvelles fonctionnalités compatibles
- **PATCH** (0): Corrections de bugs

### Historique des versions

| Version | Date | Changements majeurs |
|---------|------|---------------------|
| 2.1.0 | 2026-01-10 | Affichage compact RAM, bouton refresh, versions header |
| 2.0.0 | 2026-01-10 | Détection Proxmox, RAM slots form_factor |
| 1.5.0 | 2026-01-05 | Import PCI, champ utilisation |

## Gestion des erreurs

### Backend non accessible

Si l'API backend est down:
```
Frontend: v2.1.0
Backend: N/A
```

### Fichier version.json manquant

Si le fichier est supprimé:
```
Frontend: N/A
Backend: v2.1.0
```

### Les deux inaccessibles

En cas d'erreur totale:
```
Frontend: N/A
Backend: N/A
```

**Console**: Message d'erreur détaillé pour le débogage

## Tests

### Test 1: Vérifier affichage

1. Ouvrir `http://localhost:8087/devices.html`
2. Regarder le coin supérieur droit
3. Vérifier affichage: `Frontend: v2.1.0` et `Backend: v2.1.0`

### Test 2: Vérifier tooltips

1. Survoler "v2.1.0" pour Frontend
2. Tooltip affiché: `Build: 2026-01-10`
3. Idem pour Backend

### Test 3: Tester endpoints directement

```bash
# Frontend version
curl http://localhost:8087/version.json

# Backend version
curl http://localhost:8007/api/version
```

### Test 4: Simuler erreur backend

1. Arrêter le backend: `docker compose stop backend`
2. Recharger la page
3. Vérifier: `Backend: N/A`
4. Redémarrer: `docker compose start backend`

## Avantages

✅ **Visibilité immédiate** - Versions toujours visibles
✅ **Débogage simplifié** - Identifier rapidement les versions
✅ **Détection de cache** - Voir si le navigateur utilise une ancienne version
✅ **Compatibilité** - Vérifier que frontend et backend sont synchronisés
✅ **Non intrusif** - Petit et discret dans le coin
✅ **Tooltip informatif** - Date de build au survol
✅ **Gestion d'erreurs** - Affiche "N/A" si inaccessible

## Limitations

⚠️ **Versions manuelles** - Il faut mettre à jour les fichiers manuellement
⚠️ **Pas de build automatique** - Pas intégré au CI/CD (pour l'instant)
⚠️ **Taille fixe** - Ne s'adapte pas aux petits écrans (< 768px)

## Prochaines améliorations

1. **Build automatique**
   - Générer `version.json` à partir de git tags
   - Injecter la version dans le code Python

2. **Notification de mise à jour**
   - Comparer les versions au démarrage
   - Afficher un badge "Mise à jour disponible"

3. **Changelog intégré**
   - Cliquer sur la version → Modal avec changelog
   - Liens vers la documentation

4. **API complète /health**
   - Status: ok/error
   - Uptime
   - Database: connected/disconnected
   - Versions

5. **Responsive**
   - Masquer sur petits écrans
   - Afficher dans un menu burger

## Fichiers modifiés

1. **frontend/version.json** - Nouveau fichier de version
2. **backend/app/api/benchmark.py** (lignes 34-50) - Endpoint /version
3. **frontend/device_detail.html** (lignes 17-26) - Affichage header
4. **frontend/devices.html** (lignes 23-26) - Affichage header
5. **frontend/js/device_detail.js** (lignes 22-47) - Chargement versions
6. **frontend/js/devices.js** (lignes 30-59) - Chargement versions

## Conclusion

L'affichage des versions dans le header améliore significativement la capacité de débogage et de vérification. Il est maintenant facile de voir en un coup d'œil si les bonnes versions sont chargées, ce qui est particulièrement utile après des mises à jour ou en cas de problèmes de cache.

**Impact**: ⭐⭐⭐⭐⭐ (5/5 - essentiel pour le débogage)
**Complexité**: ⭐⭐ (2/5 - simple à implémenter)
**Maintenance**: ⭐⭐⭐ (3/5 - versions à mettre à jour manuellement)