serv_benchmark/docs/01_vision_fonctionnelle.md

01 – Vision fonctionnelle et objectifs

Nom de l’application

Nom provisoire : Linux BenchTools

Objectif : application self-hosted permettant de :

• Recenser les machines (physiques, VM, SBC type Raspberry Pi).
• Collecter des informations matérielles (CPU, RAM, GPU, stockage, réseau, carte mère, OS).
• Lancer des benchmarks standardisés via un script client exécuté sur les machines.
• Recevoir et stocker les résultats de bench sur un serveur central.
• Calculer une note globale et des sous-scores (CPU, mémoire, disque, réseau, GPU).
• Afficher un dashboard triant les machines par performance globale.
• Associer des liens constructeurs et des documents (PDF / images) à chaque machine.
• tu verifiera bien sur la coherence entre tous les fichier de consigne de prompt et si le choix des outils est cohérent

L’application doit être :

• Self-hosted sur une machine Linux (Debian) au format Docker.
• Légère (SQLite, pas de dépendance à une grosse base).
• Accessible sur le réseau local (via reverse proxy existant).
• Exploitable autant pour des serveurs que des PC ou des VMs.

---

Rôles et usages

Rôle principal : utilisateur/admin unique (Gilles)

Actions possibles :

• Ajouter/modifier une machine (device) et ses métadonnées (description, localisation, tags).
• Visualiser les informations hardware associées à une machine.
• Lancer un bench sur une machine en copiant une commande fournie par l’interface.
• Visualiser l’historique des benchmarks d’une machine.
• Consulter les notes globales et par catégorie (CPU, RAM, disque, réseau, GPU).
• Ajouter/éditer des liens vers les sites constructeurs.
• Uploader des notices PDF, factures, schémas, photos.

---

Fonctionnalités principales (MVP)

1. Gestion des machines (devices)

   • CRUD basique :
     • Créer un device (ou auto-création à la réception d’un bench).
     • Lire les infos d’un device.
     • Modifier la description, la localisation, les tags.
   • Un device représente une machine logique (hostname ou nom choisi).

2. Snapshots hardware

   • À chaque bench, un snapshot de l’état matériel et OS est enregistré :
     • CPU (modèle, cœurs, threads, fréquences, cache, vendor).
     • RAM (total, slots, type, capacités).
     • GPU (modèle, mémoire, vendor).
     • Disques (liste, type, taille, interface, SMART résumé).
     • Réseau (interfaces, vitesses, IPs).
     • Carte mère (vendor, modèle, BIOS).
     • OS (nom, version, kernel, architecture, type machine : bare metal / VM).
   • Ces infos sont liées à un hardware_snapshot et référencées par un benchmark.

3. Benchmarks

   • Réception d’un JSON produit par un script Bash exécuté sur la machine.
   • Enregistrement d’un benchmark avec :
     • Date/heure du run.
     • Version du script client.
     • Scores par catégorie : cpu_score, memory_score, disk_score, network_score, gpu_score.
     • global_score calculé selon une formule configurable (par ex. moyenne pondérée).
     • Détails bruts en JSON (details_json) pour audit.

4. Liens constructeur

   • Attacher à un device des liens HTTP :
     • Fiche produit constructeur.
     • Page support / BIOS / drivers.
     • Documentation technique.

5. Documents

   • Upload de fichiers (surtout PDF) associés à un device :
     • Notices / manuels.
     • Factures.
     • Photos / schémas.
   • Stockage sur disque, références dans SQLite.

6. Dashboard Web

   • Page d’accueil :
     • Statistiques globales (nombre de devices, nombre total de benchmarks, date dernier bench, score moyen).
     • Tableau trié par global_score décroissant.
   • Indicateur compact par ligne :
     • Hostname + description.
     • Dernier global_score.
     • Détail CPU/Mem/Disk/Net/GPU du dernier bench.
   • Section "Quick bench script" :
     • Affichage de la commande shell à copier/coller pour exécuter le script client.

---

Non-objectifs (MVP)

• Pas de multi-tenant ni de gestion avancée de droits utilisateurs.
• Pas de monitoring temps réel (ce n’est pas un outil de supervision).
• Pas de support Windows/macOS dans la première version (Linux seulement).
• Pas d’agent resident/daemon permanent sur les clients (simple script à exécuter ponctuellement).

---

Contraintes techniques

• Backend en Python (FastAPI recommandé).
• Base de données : SQLite (fichier sur disque).
• WebUI simple (HTML/CSS/JS minimal, éventuellement HTMX).
• Déploiement via Docker + docker-compose.
• Script client en Bash (priorité Debian/Ubuntu, extensible ensuite).

---

Critères de réussite (MVP)

• Être capable de :
  • Déployer l’app via docker-compose up -d.
  • Copier une commande depuis le Dashboard, l’exécuter sur une machine Linux, et voir :
    • Le device apparaître (ou se mettre à jour).
    • Un nouveau benchmark visible dans l’interface.
  • Voir la machine triée correctement dans le dashboard par global_score.
• Pouvoir attacher au moins un PDF à un device et le télécharger depuis l’interface.