serv_benchmark/GEMINI.md

Linux BenchTools - Contexte du Projet

Aperçu du Projet

Linux BenchTools est une application auto-hébergée de benchmarking et de gestion d'inventaire matériel pour les machines Linux (physiques, VM, SBC comme Raspberry Pi). Elle permet aux utilisateurs de :

• Collecter les spécifications matérielles (CPU, RAM, Stockage, Réseau, GPU).
• Exécuter des benchmarks standardisés.
• Calculer des scores comparables et afficher des classements.
• Gérer l'inventaire matériel (machines et périphériques comme les clés USB, câbles, etc.).
• Générer des QR codes pour le suivi physique des actifs.
• Stocker la documentation associée (PDF, factures).

Stack Technique

• Backend : Python 3.11+, FastAPI, SQLAlchemy, Pydantic.
• Frontend : HTML5, CSS3, JavaScript Vanilla (servi via Nginx).
• Base de données : SQLite (Bases de données séparées pour les Benchmarks et les Périphériques).
• Script Client : Bash (bench.sh) pour la collecte de données sur les machines cibles.
• Infrastructure : Docker & Docker Compose.
• Autre : Go (placeholder dans bench_go, potentiellement pour un futur client).

Structure des Répertoires

• backend/ : Code source de l'application FastAPI.
  • app/ : Paquet principal de l'application.
    • api/ : Points d'entrée (endpoints) de l'API.
    • core/ : Paramètres de configuration et de sécurité.
    • models/ : Modèles de base de données SQLAlchemy.
    • schemas/ : Schémas de données Pydantic.
    • utils/ : Fonctions utilitaires (ex: logique de calcul des scores).
  • data/ : Stockage des bases de données SQLite (data.db, peripherals.db).
  • uploads/ : Stockage des documents et images téléchargés.
• frontend/ : Actifs statiques du frontend (HTML, CSS, JS).
• bench_go/ : Implémentation Go du client de benchmark (en cours de développement).
• config/ : Fichiers de configuration YAML pour divers modules (types de périphériques, emplacements).
• docs/ : Documentation complète du projet.
• scripts/ : Scripts utilitaires.
• docker-compose.yml : Définition des services (backend, frontend/nginx).
• .env.example : Modèle pour les variables d'environnement.

Composants Clés

Backend (FastAPI)

Le backend expose une API REST pour :

• Recevoir les données de benchmark via un payload JSON.
• Servir les données au tableau de bord frontend.
• Gérer l'inventaire des périphériques.
• Gérer les téléchargements de fichiers (images, docs).

Il utilise deux bases de données SQLite :

1. data.db : Pour les benchmarks, les appareils et les documents associés.
2. peripherals.db : Spécifiquement pour le module d'inventaire des périphériques.

Frontend (JS Vanilla)

Un tableau de bord léger stylisé avec le thème Monokai Dark. Il interagit avec l'API backend pour afficher des tableaux, des détails et des formulaires. Aucun build n'est requis ; il est servi directement par Nginx.

Client de Bench (Bash)

Le script bench.sh est exécuté sur la machine cible. Il lance des outils comme sysbench, fio, iperf3 et glmark2, puis envoie les résultats à l'API backend.

Module Périphériques

Un ensemble de fonctionnalités distinctes pour la gestion des articles en inventaire. Il comprend :

• Gestion hiérarchique des emplacements.
• Génération de QR codes (librairie qrcode).
• Traitement d'images (librairie Pillow) pour les vignettes (thumbnails).
• Importation automatisée depuis lsusb.

Développement & Utilisation

Installation

1. Cloner : git clone ...
2. Installer : Lancer ./install.sh (automatise la création du .env et la configuration) OU configuration manuelle via Docker Compose.
3. Lancer : docker compose up -d

Variables d'Environnement

Variables clés dans le .env :

• API_TOKEN : Jeton secret pour authentifier les clients de benchmark.
• DATABASE_URL : Chemin vers la base de données SQLite principale.
• PERIPHERALS_DB_URL : Chemin vers la base de données SQLite des périphériques.
• UPLOAD_DIR : Chemin pour le stockage des fichiers.

Exécuter un Benchmark

Exécuter sur la machine cible :

curl -s <BACKEND_URL>/scripts/bench.sh | bash -s -- --server <BACKEND_URL>/api/benchmark --token <API_TOKEN> --device <DEVICE_NAME>

Documentation

Une documentation exhaustive est disponible dans docs/, notamment :

• 06_backend_architecture.md : Détails sur l'architecture backend.
• README_PERIPHERALS.md : Guide pour le module périphériques.
• 02_model_donnees.md : Schéma de la base de données.

Conventions de Codage

• Python : Les "type hints" sont largement utilisés (modèles Pydantic).
• Style : Respecte le standard PEP 8.
• Commits : Messages descriptifs.