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

{
  "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)

@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)

<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)

<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)

// 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):

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

# 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)