From d55a56b91f61e782c4d9c32c2b7584d193b39baa Mon Sep 17 00:00:00 2001 From: Gilles Date: Sun, 7 Dec 2025 14:16:58 +0100 Subject: [PATCH] readme --- 01_vision_fonctionnelle.md | 1 + 05_webui_design.md | 192 +++++++++++++++++++++++++ 06_backend_architecture.md | 216 ++++++++++++++++++++++++++++ 08_installation_bootstrap.md | 238 +++++++++++++++++++++++++++++++ 09_tests_qualite.md | 263 +++++++++++++++++++++++++++++++++++ 10_roadmap_evolutions.md | 216 ++++++++++++++++++++++++++++ 6 files changed, 1126 insertions(+) create mode 100644 05_webui_design.md create mode 100644 06_backend_architecture.md create mode 100644 08_installation_bootstrap.md create mode 100644 09_tests_qualite.md create mode 100644 10_roadmap_evolutions.md diff --git a/01_vision_fonctionnelle.md b/01_vision_fonctionnelle.md index 5afd9be..689a856 100644 --- a/01_vision_fonctionnelle.md +++ b/01_vision_fonctionnelle.md @@ -12,6 +12,7 @@ Objectif : application self-hosted permettant de : - 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. diff --git a/05_webui_design.md b/05_webui_design.md new file mode 100644 index 0000000..1934d0e --- /dev/null +++ b/05_webui_design.md @@ -0,0 +1,192 @@ + +# 05 – Design WebUI (structure, pages, composants) + +Objectif : définir l’interface utilisateur de Linux BenchTools, les pages, les composants, l’organisation visuelle et les interactions nécessaires. + +--- + +# 1. Principes généraux + +- Interface orientée **observabilité** des performances machines. +- Style sombre **Monokai-like**. +- Pages structurées en **cartes** et **tableaux lisibles**. +- Navigation : **Dashboard**, **Devices**, **Settings**. +- Composants réutilisables : badges score, cartes hardware, tableaux benchmark. + +--- + +# 2. Pages de la WebUI + +## 2.1. Dashboard (`/`) +Présente un aperçu du parc machines et un classement global. + +### Contenu : +- **Stats globales** + - Nombre de devices + - Nombre total de benchmarks + - Score global moyen + - Dernier bench reçu +- **Tableau Top Devices** + - Rang + - Hostname + - Description + - Score global + - Scores CPU/MEM/DISK/NET/GPU + - Dernier run +- **Bloc “Quick Bench Script”** + - Commande à copier pour exécuter un bench sur une nouvelle machine. + +--- + +## 2.2. Liste Devices (`/devices`) + +- Tableau paginé et filtrable +- Colonnes : + - Hostname + - Description + - Location + - Tags + - Dernier Score + - Dernier Bench + - Bouton “Voir” + +Barre de recherche : filtre hostname / tags / description. + +--- + +## 2.3. Page Device Détail (`/devices/{id}`) + +### Sections : + +#### A. Bandeau principal +- Hostname +- Description +- Tags +- Localisation / Owner + +#### B. Résumé Hardware +- CPU : modèle, cores, threads, fréquences +- RAM : total, slots utilisés, détail +- GPU +- Stockage (NVMe/SSD/HDD) +- Réseau +- Carte mère / BIOS +- OS / kernel + +#### C. Dernier Benchmark +- Score global + badge couleur +- Scores CPU / MEM / DISK / NET / GPU +- Timestamp +- Bouton “Voir JSON complet” + +#### D. Onglets + +1. **Summary** +2. **Benchmarks** + - Tableau simple + - Évolution future en graphe +3. **Documents** + - Upload PDF/images + - Liste des documents + - Boutons download/delete +4. **Links** + - Liste des liens constructeurs + - Form ajout + - Edit / Delete + +--- + +## 2.4. Settings (`/settings`) + +Champs configurables : +- Bench server URL +- Default iperf-server +- Token API (lecture seule) +- Commande bench générée automatiquement + +--- + +# 3. Style visuel (Monokai Dark) + +### Couleurs +- Fond général : `#1e1e1e` +- Cartes : `#2d2d2d` +- Texte principal : `#f8f8f2` +- Texte secondaire : `#cccccc` +- Success : `#a6e22e` +- Warning : `#fd971f` +- Danger : `#f92672` + +### Composants +- **Badge Score** + - 0–50 : rouge + - 51–75 : orange + - 76–100 : vert +- **Cartes Hardware** + - Layout en 2 ou 3 colonnes +- **Tableaux** + - Style striped + hover highlight + +--- + +# 4. Mockups ASCII + +## Dashboard +``` ++---------------------------------------------------------------------------+ +| Linux BenchTools – Dashboard | ++---------------------------------------------------------------------------+ +| Stats | +| Devices: 12 Benchmarks: 47 Avg Score: 78.4 Last: 2025‑12‑07 | ++---------------------------------------------------------------------------+ +| Top Devices | ++---------------------------------------------------------------------------+ +| # | Hostname | Score | CPU | MEM | DISK | NET | GPU | Last Run | +|---------------------------------------------------------------------------| +| 1 | elitedesk-800g3 | 92 | 90 | 95 | 94 | 88 | -- | 10:32 | ++---------------------------------------------------------------------------+ +| Quick Bench Script | +| curl -s https://.../bench.sh | bash -s -- --server ... --token XXXX | ++---------------------------------------------------------------------------+ +``` + +## Page Device +``` +Device: elitedesk-800g3 +Location: Bureau Tags: lab, dev + +Hardware Summary: + CPU: Intel i7‑6700 (4C/8T, 3.4 → 4.0 GHz) + RAM: 64GB (4×16GB) + GPU: Intel HD 530 + Storage: NVMe 1TB + HDD 2TB + Network: eth0 1Gbps + OS: Debian 12 / Kernel 6.1 + +Last Benchmark: + Global Score: 92 [GREEN] + CPU 90 | MEM 95 | DISK 94 | NET 88 | GPU -- + Run: 2025‑12‑07 10:32 + +Tabs: [Summary] [Benchmarks] [Documents] [Links] +``` + +--- + +# 5. API utilisée par le frontend + +- `/api/devices` +- `/api/devices/{id}` +- `/api/devices/{id}/benchmarks` +- `/api/devices/{id}/docs` +- `/api/docs/{id}/download` +- `/api/devices/{id}/links` + +--- + +# 6. Améliorations futures + +- Graphiques d’évolution des scores (Chart.js) +- Mode mobile +- Compare devices +- Notifications en cas de baisse anormale de performance diff --git a/06_backend_architecture.md b/06_backend_architecture.md new file mode 100644 index 0000000..6f3bd7f --- /dev/null +++ b/06_backend_architecture.md @@ -0,0 +1,216 @@ + +# 06 – Architecture Backend & Déploiement (FastAPI + Uvicorn + Docker) + +Objectif : définir la structure technique du backend, l'organisation du code, les dépendances, +le déploiement via Docker, et les bonnes pratiques de maintenance. + +--- + +# 1. Architecture générale du backend + +Le backend repose sur : + +- Python **3.11+** +- **FastAPI** (framework web) +- **Uvicorn** (serveur ASGI) +- **SQLite** (stockage local) +- **SQLAlchemy** (ORM) +- **Pydantic** (validation des schémas) +- Docker (déploiement) +- Arborescence claire modulaire + +--- + +# 2. Arborescence recommandée + +``` +backend/ +│ +├── app/ +│ ├── api/ +│ │ ├── benchmark.py +│ │ ├── devices.py +│ │ ├── docs.py +│ │ ├── links.py +│ │ └── __init__.py +│ │ +│ ├── core/ +│ │ ├── config.py +│ │ ├── security.py +│ │ └── __init__.py +│ │ +│ ├── models/ +│ │ ├── device.py +│ │ ├── hardware_snapshot.py +│ │ ├── benchmark.py +│ │ ├── manufacturer_link.py +│ │ ├── document.py +│ │ └── __init__.py +│ │ +│ ├── schemas/ +│ │ ├── benchmark.py +│ │ ├── device.py +│ │ ├── hardware.py +│ │ ├── document.py +│ │ ├── link.py +│ │ └── __init__.py +│ │ +│ ├── db/ +│ │ ├── base.py +│ │ ├── session.py +│ │ ├── init_db.py +│ │ └── __init__.py +│ │ +│ ├── utils/ +│ │ ├── scoring.py +│ │ └── __init__.py +│ │ +│ ├── main.py +│ └── __init__.py +│ +├── Dockerfile +├── requirements.txt +└── README.md +``` + +--- + +# 3. Dépendances backend (requirements.txt) + +``` +fastapi +uvicorn +sqlalchemy +alembic +pydantic +python-multipart +jinja2 +aiofiles +``` + +--- + +# 4. Fonctionnement principal + +## 4.1 main.py + +- Initialise FastAPI +- Charge les routes `/api/*` +- Initialise la base SQLite +- Expose un `GET /api/health` + +--- + +# 5. Configuration (core/config.py) + +Variables chargées via environnement : + +- `API_TOKEN` +- `DATABASE_URL` → `sqlite:///./data.db` +- `UPLOAD_DIR` → `./uploads` + +--- + +# 6. Déploiement Docker + +## 6.1 Dockerfile + +``` +FROM python:3.11-slim + +WORKDIR /app + +COPY requirements.txt . +RUN pip install --no-cache-dir -r requirements.txt + +COPY app ./app + +RUN mkdir -p /app/uploads /app/data + +ENV API_TOKEN=CHANGE_ME +ENV DATABASE_URL=sqlite:////app/data/data.db +ENV UPLOAD_DIR=/app/uploads + +CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8007"] +``` + +--- + +## 6.2 docker-compose.yml + +``` +version: "3.9" + +services: + backend: + build: ./backend + container_name: linux_benchtools_backend + ports: + - "8007:8007" + volumes: + - ./backend/data:/app/data + - ./backend/uploads:/app/uploads + environment: + API_TOKEN: "SUPER_SECRET_TOKEN" + DATABASE_URL: "sqlite:////app/data/data.db" + UPLOAD_DIR: "/app/uploads" + restart: unless-stopped +``` + +--- + +# 7. Gestion des documents (PDF, images) + +- Stockés dans `/app/uploads` +- Nommage unique (hash) +- Entrée correspondante dans la BDD +- Accessibles via `/api/docs/{id}/download` + +--- + +# 8. Pipeline d’un benchmark + +1. Le client exécute `bench.sh` +2. Un JSON complet est envoyé vers POST `/api/benchmark` +3. Vérification du token +4. Recherche ou création du device +5. Création d’un hardware snapshot +6. Création d’un benchmark +7. Calcul / stockage du score global +8. Réponse `{status: "ok", ...}` + +--- + +# 9. Module scoring (utils/scoring.py) + +Calcule : + +``` +global_score = + cpu * 0.30 + + mem * 0.20 + + disk * 0.25 + + net * 0.15 + + gpu * 0.10 +``` + +Utilise les scores normalisés reçus depuis le client. + +--- + +# 10. Sécurité + +- API Token unique pour tous les clients +- Upload limité en taille +- CORS restreint au LAN si besoin +- Aucun endpoint destructif sans authentification + +--- + +# 11. Maintenance + +- Backup SQLite via cron +- Logs Docker +- Vérification santé via `/api/health` +- Ajout futur : export JSON/CSV global + diff --git a/08_installation_bootstrap.md b/08_installation_bootstrap.md new file mode 100644 index 0000000..48a1bfd --- /dev/null +++ b/08_installation_bootstrap.md @@ -0,0 +1,238 @@ + +# 08 – Script d'installation & Bootstrapping (install.sh) + +Objectif : fournir un guide exhaustif et un script d’installation automatisée de l’application +**Linux BenchTools** (backend + frontend + dépendances) ainsi que son organisation dans le dépôt. + +Ce fichier décrit : + +- Le rôle du script `install.sh` +- Les prérequis système +- L’installation via Docker ou native +- La génération automatique de l’arborescence +- Les variables d’environnement nécessaires +- Le lancement des services + +--- + +# 1. Objectifs du script `install.sh` + +Le script doit : + +1. Vérifier les prérequis (Docker, Docker Compose, Python si installation native) +2. Créer l'arborescence du projet si inexistante +3. Générer les fichiers `.env` nécessaires +4. Installer le backend (FastAPI) +5. Installer le frontend (fichiers statiques) +6. Construire et lancer les conteneurs +7. Vérifier que l’application fonctionne via un health check +8. Afficher les URL utiles et les commandes d’usage + +--- + +# 2. Arborescence créée automatiquement + +``` +linux-benchtools/ +│ +├── backend/ +│ ├── app/ +│ ├── Dockerfile +│ ├── requirements.txt +│ └── data/ (auto) +│ +├── frontend/ +│ ├── index.html +│ ├── devices.html +│ ├── device_detail.html +│ ├── settings.html +│ ├── css/ +│ └── js/ +│ +├── uploads/ (auto) +│ +├── docker-compose.yml +├── .env +└── install.sh +``` + +--- + +# 3. Prérequis système + +Le script doit vérifier la présence de : + +- **curl** +- **git** +- **Docker** +- **Docker Compose (plugin)** + +Si absent → afficher un message clair (avec commande d’installation Debian/Ubuntu). + +Exemple : + +```bash +if ! command -v docker >/dev/null 2>&1; then + echo "[ERREUR] Docker n’est pas installé." + echo "Installez-le avec :" + echo " curl -fsSL https://get.docker.com | sh" + exit 1 +fi +``` + +--- + +# 4. Fichier `.env` généré + +Le script crée automatiquement un fichier `.env` si absent. + +Exemple : + +``` +API_TOKEN=$(openssl rand -hex 32) +DATABASE_URL=sqlite:////app/data/data.db +UPLOAD_DIR=/app/uploads +BACKEND_PORT=8007 +FRONTEND_PORT=8087 +``` + +--- + +# 5. docker-compose.yml généré + +Le script crée un fichier minimal : + +``` +version: "3.9" + +services: + backend: + build: ./backend + ports: + - "${BACKEND_PORT}:8007" + volumes: + - ./backend/data:/app/data + - ./uploads:/app/uploads + env_file: .env + restart: unless-stopped + + frontend: + image: nginx:latest + volumes: + - ./frontend:/usr/share/nginx/html:ro + ports: + - "${FRONTEND_PORT}:80" + restart: unless-stopped +``` + +--- + +# 6. Installation native (option) + +Si l'utilisateur passe `install.sh --native` : + +- Installation Python + venv +- Installation requirements.txt +- Exécution via : + +``` +uvicorn app.main:app --host 0.0.0.0 --port 8007 +``` + +Frontend servi via un simple `python3 -m http.server`. + +--- + +# 7. Vérification de l’installation + +Une fois les services lancés : + +``` +curl -s http://localhost:${BACKEND_PORT}/api/health +``` + +Si réponse : + +``` +{"status":"ok"} +``` + +→ installation validée. + +--- + +# 8. Affichage final après installation + +Le script doit afficher : + +``` +Installation terminée ! + +Backend API : http://localhost:8007 +Frontend UI : http://localhost:8087 +Token API : + +Pour exécuter un benchmark sur une machine : +curl -s | bash -s -- --server http://:8007/api/benchmark --token +``` + +--- + +# 9. Structure du script `install.sh` + +### Exemple de squelette : + +```bash +#!/usr/bin/env bash + +set -e + +echo "[INFO] Vérification des prérequis..." +# test docker, docker compose, curl... + +echo "[INFO] Création des dossiers..." +mkdir -p backend/data +mkdir -p uploads + +echo "[INFO] Génération du fichier .env..." +if [ ! -f .env ]; then + API_TOKEN=$(openssl rand -hex 32) + cat < .env +API_TOKEN=$API_TOKEN +DATABASE_URL=sqlite:////app/data/data.db +UPLOAD_DIR=/app/uploads +BACKEND_PORT=8007 +FRONTEND_PORT=8087 +EOF +fi + +echo "[INFO] Construction des containers..." +docker compose build + +echo "[INFO] Lancement..." +docker compose up -d + +echo "[INFO] Vérification..." +sleep 2 +curl -s http://localhost:8007/api/health || { + echo "[ERREUR] Le backend ne répond pas." + exit 1 +} + +echo "----------------------------------------------" +echo " Linux BenchTools installé avec succès !" +echo " Backend : http://localhost:8007" +echo " Frontend : http://localhost:8087" +echo " Token : $(grep API_TOKEN .env | cut -d= -f2)" +echo "----------------------------------------------" +``` + +--- + +# 10. Améliorations futures + +- Choix interactif du port +- Installation sans Docker (automatique) +- Ajout d'un mode "cluster" (plusieurs workers backend) +- Génération automatique d’un certificat TLS + diff --git a/09_tests_qualite.md b/09_tests_qualite.md new file mode 100644 index 0000000..55f2522 --- /dev/null +++ b/09_tests_qualite.md @@ -0,0 +1,263 @@ + +# 09 – Stratégie de tests, validation et qualité pour Linux BenchTools + +Objectif : définir comment tester et valider chaque brique de l’application +(backend, script bench, frontend), afin d’assurer fiabilité, reproductibilité des mesures +et facilité de maintenance. + +Ce document sert de guide pour écrire les tests et scénarios de validation manuelle. + +--- + +# 1. Périmètre des tests + +Les tests couvrent : + +1. **Backend API** + - Validation des endpoints + - Validation de la persistance en base + - Validation de la sécurité (token) +2. **Script client `bench.sh`** + - Fonctionnement sur différentes machines Debian/Ubuntu + - Gestion des erreurs (outils manquants, serveur indisponible) + - Qualité du JSON envoyé +3. **Frontend WebUI** + - Rendu des pages (Dashboard, Devices, Device Detail, Settings) + - Consommation correcte de l’API + - UX minimale (lisibilité, tri, navigation) +4. **Tests de bout en bout (E2E)** + - Exécution complète d’un bench depuis un client → apparition dans le Dashboard. + +--- + +# 2. Tests Backend + +## 2.1. Types de tests + +- **Tests unitaires** : fonctions isolées (scoring, mapping JSON → modèles). +- **Tests d’intégration** : endpoints FastAPI avec base SQLite de test. +- **Tests E2E API** : envoi d’un payload complet depuis un script de test. + +Framework recommandé : +- `pytest` +- `httpx` ou client de test FastAPI + +## 2.2. Cas de test principaux + +### a) POST /api/benchmark + +- [OK] Payload complet, token valide : + - Retourne 200 + - Crée un `device` si inexistant + - Crée un `hardware_snapshot` + - Crée un `benchmark` +- [OK] Device existant : + - Réutilise le `device` +- [ERR] Token manquant : + - 401 +- [ERR] Token incorrect : + - 401 +- [ERR] JSON invalide : + - 400 + +### b) GET /api/devices + +- [OK] Base vide → items = []. +- [OK] Avec plusieurs devices et benchmarks : + - Retourne un `last_benchmark` cohérent. +- [OK] Paramètres `page`, `page_size` : + - Pagination effective. + +### c) GET /api/devices/{id} + +- [OK] Device existant : + - Retourne résumé, snapshot, dernier benchmark. +- [ERR] Device inexistant : + - 404. + +### d) Liens constructeur + +- [OK] CRUD complet sur `/api/devices/{id}/links`. +- [ERR] URL invalide (peut être toléré ou validé selon règle). + +### e) Documents + +- [OK] Upload PDF : + - Fichier stocké physiquement + - Entrée BDD créée +- [OK] Download : + - Renvoie bon `Content-Type` +- [ERR] doc_id invalide : + - 404. + +--- + +# 3. Tests Script client (bench.sh) + +## 3.1. Contexte + +Les tests sur `bench.sh` sont principalement : +- des tests manuels guidés +- des tests automatisables partiellement (CI dans un container Docker). + +## 3.2. Cas de test + +### a) Aide & usage + +- `bench.sh --help` → affiche usage. +- Sans arguments → erreur claire. + +### b) Prérequis + +- Si `curl`, `jq`, `sysbench`, `fio` manquants : + - message explicite + - tentative d’installation si possible (apt-get) + - en cas d’échec, test concerné désactivé mais script continue. + +### c) Exécution minimale + +- `bench.sh --server http://backend:8007/api/benchmark --token XXX` : + - Détecte le hostname + - Exécute les tests par défaut + - Envoie un JSON valide (vérifiable via logs backend). + +### d) Modes d’options + +- `--short` : + - Durées de tests CPU/mémoire/disk raccourcies +- `--skip-network` : + - Aucun test iperf3, bloc `results.network` absent ou null +- `--iperf-server` avec serveur iperf opérationnel : + - Champs réseau correctement renseignés. + +### e) Gestion des erreurs réseau + +- Backend down : + - Message d’erreur clair + - Code HTTP ≠ 200 connu +- Iperf3 indisponible : + - Bloc network absent/null + +--- + +# 4. Tests Frontend + +## 4.1. Smoke tests (manuels) + +- Accès à : + - `/` → Dashboard + - `/devices` + - `/devices/{id}` + - `/settings` +- Vérification du rendu : + - Aucune erreur JS console + - Chargement des datas via API + - Tri de base dans les tableaux + +## 4.2. Tests fonctionnels (scénarios) + +### Scénario 1 : Premier lancement + +1. Déployer l’application. +2. Vérifier Dashboard vide, message “Aucun device”. +3. Exécuter `bench.sh` sur une machine. +4. Rafraîchir Dashboard : + - Device apparaît avec score. + +### Scénario 2 : consultation d’un device + +1. Cliquer sur un device dans le Dashboard. +2. Page détail : + - Hardware résumé cohérent. + - Dernier benchmark affiché. +3. Onglet Benchmarks : + - Historique listé. + +### Scénario 3 : Documents + +1. Aller dans onglet Documents d’un device. +2. Uploader un PDF. +3. Vérifier sa présence dans la liste. +4. Télécharger pour confirmer. + +### Scénario 4 : Liens constructeur + +1. Onglet Links d’un device. +2. Ajouter un lien avec label + URL. +3. Vérifier qu’il est cliquable. +4. Tester suppression. + +--- + +# 5. Tests E2E (de bout en bout) + +Objectif : couvrir la chaîne complète depuis la machine cliente jusqu’au Dashboard. + +### Scénario E2E type + +1. Lancer backend + frontend via `docker compose up`. +2. Déployer `bench.sh` sur un client Debian. +3. Exécuter : + +```bash +curl -s https://.../bench.sh | bash -s -- \ + --server http://IP_BACKEND:8007/api/benchmark \ + --token XXX \ + --iperf-server 10.0.0.10 +``` + +4. Vérifier côté backend (logs) qu’un benchmark a été créé. +5. Ouvrir le Dashboard : + - Device présent, scores visibles. + +--- + +# 6. Données de test + +Créer un répertoire `tests/data/` contenant : + +- Exemples de payload JSON de bench : + - `bench_full.json` (tous tests) + - `bench_no_gpu.json` + - `bench_short.json` +- Scripts auxiliaires : + - `send_bench_payload.py` (envoi direct d’un payload pour tests). + +--- + +# 7. Automatisation CI (optionnel) + +Intégration avec : + +- GitHub Actions +- Gitea Actions / Drone / Woodpecker + +Tâches CI typiques : + +1. `pytest` sur le backend +2. Lancement d’un backend en mode test +3. Envoi d’un payload JSON factice +4. Vérification de la réponse HTTP + +--- + +# 8. Critères de qualité + +L’application sera considérée comme “OK” pour usage perso si : + +- Au moins 1 test unitaire par endpoint critique +- Un scénario E2E réussi +- `bench.sh` fonctionne sur : + - 1 machine physique + - 1 VM +- Les erreurs d’auth/token sont gérées proprement +- Le Dashboard reste utilisable avec plusieurs dizaines de devices et benchmarks + +--- + +# 9. Améliorations possibles + +- Ajout de tests de charge (Gatling / k6) sur le backend +- Ajout de tests de non-régression des scores (baseline) +- Ajout de tests visuels (Playwright, Cypress) +- Intégration d’un badge “build/test status” dans le README principal diff --git a/10_roadmap_evolutions.md b/10_roadmap_evolutions.md new file mode 100644 index 0000000..b04be8d --- /dev/null +++ b/10_roadmap_evolutions.md @@ -0,0 +1,216 @@ + +# 10 – Roadmap & évolutions futures pour Linux BenchTools + +Objectif : lister les évolutions possibles de l’application, organisées par phases, avec une vision +à court, moyen et long terme. Ce fichier sert de base pour prioriser les développements. + +--- + +# 1. Vision globale + +Linux BenchTools doit évoluer depuis un simple serveur de benchmarks centralisés vers : + +- Un **inventaire matériel dynamique** de ton parc. +- Un **historique de performance** exploitable (avant/après upgrade, changement de config, etc.). +- Un **outil d’aide à la décision** (quelle machine est la plus adaptée pour tel usage). +- Un **hub de diagnostics** (détection de régression de perf, disques fragiles, réseau bridé…). + +--- + +# 2. Phase 1 – MVP (déjà spécifiée dans les fichiers 01 → 09) + +Fonctionnalités : + +- Réception de benchmarks via `bench.sh` +- Stockage dans SQLite +- Dashboard avec classement des machines +- Détail device + historique de benchmarks +- Liens constructeur +- Upload de documents (PDF, images) +- Script d’installation (Docker / compose) + +Objectif : +Avoir une base utilisable **en production perso** sur ton infra maison. + +--- + +# 3. Phase 2 – Améliorations UX & stabilité + +## 3.1. Frontend + +- Tri avancé sur les colonnes (score, date dernier bench, hostname). +- Filtre par tags, type de machine (bare-metal / VM / SBC). +- Ajout d’icônes simples (type machine, OS, réseau 1G/2.5G/10G…). +- Page “Benchmarks” globale (tous les benchmarks, filtrables par device). + +## 3.2. Backend + +- Meilleure gestion des erreurs côté API (messages clairs, codes cohérents). +- Pagination plus fine (page_size configurable). +- Logging structuré (JSON logs optionnels). +- Limitation taille payload JSON (protection simple). + +## 3.3. Script client + +- Mode “dry-run” (afficher JSON sans l’envoyer). +- Mode “debug” (log détaillé des commandes). + +--- + +# 4. Phase 3 – Historisation avancée & graphes + +## 4.1. Graphes dans la WebUI + +- Sur page device : + - Graphique du **global_score** sur le temps. + - Graphiques séparés : + - CPU score vs temps + - Mémoire score vs temps + - Disque score vs temps + - Réseau score vs temps +- Lib JS possible : + - Chart.js ou ECharts (simple, self-hosté). + +## 4.2. Comparaison de benchmarks + +- Comparer 2 benchmarks d’un même device : + - Afficher les différences (avant/après ajout RAM, changement SSD…). +- Comparer 2 devices : + - Table des scores côte-à-côte. + - Exemple d’usage : + - “Quelle machine est la meilleure candidate pour un nouveau service Docker ?” + +--- + +# 5. Phase 4 – Détection de régressions & alertes + +## 5.1. Détection automatique + +- Calcul d’un “baseline” par device : + - par exemple moyenne des N meilleurs scores. +- Lors d’un nouveau bench : + - si le score est inférieur de X% à la baseline → marquer en **WARNING**. +- Indicateurs : + - CPU plus lent + - Disque sensiblement plus lent (fragilité SSD/HDD) + - Réseau plus lent (câble / switch / config ?) + +## 5.2. Alertes + +- Marquage visuel dans la WebUI (icône warning). +- Export JSON ou webhook Webhook simple : + - POST vers un endpoint externe (ex: Home Assistant, Node-RED, etc.) +- Intégration possible : + - Appel HTTP vers Home Assistant pour créer une notification. + +--- + +# 6. Phase 5 – Intégrations externes + +## 6.1. Intégration Gitea / Git + +- Stocker le dépôt `bench.sh` dans une forge (déjà le cas). +- Ajouter : + - Liens vers la version exacte du script qui a généré tel bench. +- Option : + - Webhook Gitea → déclencher bench sur un device après un changement de config. + +## 6.2. Intégration Home Assistant + +- Exposer certains indicateurs via une API ou MQTT : + - Dernier score par device + - Warn/alert sur régression +- Dashboard HA : + - Carte des machines avec état “OK / Warning / Error”. + +## 6.3. Intégration Prometheus / Grafana (option) + +- Exporter métriques (nombre de devices, benchs, scores moyens) via `/metrics`. +- Visualisation dans Grafana. + +--- + +# 7. Phase 6 – Extensions techniques + +## 7.1. Support multi-OS + +- Extension `bench.sh` pour : + - Linux non-Debian (Arch, Fedora) + - macOS (optionnel) + - Windows (PowerShell script séparé) + +## 7.2. Agents “semi-persistants” + +- Mode où un service systemd sur certains serveurs : + - exécute un bench toutes les X semaines. + - envoie automatiquement les données au backend. + +## 7.3. Export / Import + +- Export complet de : + - devices + - benchmarks + - hardware_snapshots +- Formats : + - JSON + - CSV (pour certains tableaux) +- Import depuis un ancien fichier → migration facile vers nouvelle instance. + +--- + +# 8. Phase 7 – UX & ergonomie avancées + +- Tags et “groupes” de devices (ex: “serveurs prod”, “lab”, “RPi”, “Proxmox nodes”). +- Vues filtrées : + - Vue “serveurs” + - Vue “VM Proxmox” + - Vue “SBC (RPi, OPi, etc.)” +- Possibilité de nommer des “profils” : + - ex: “Profil NVR”, “Profil VM/Proxmox”, “Profil PC Gaming” + - et voir les devices qui matchent le mieux chaque profil en fonction de leur score. + +--- + +# 9. Idées long terme (si tu veux pousser très loin) + +- Auto-détection hardware via une petite API agent qui tourne sur les machines en continu (au-delà du script ponctuel). +- Benchmark réseau multi-nœuds : + - topologie logical de ton réseau + - latences et débits entre plusieurs points. +- Vue “Carte du réseau” : + - affichage graphique des performances entre différentes machines. +- Plugins : + - Ajouter une API plugin pour créer ses propres tests (ex: bench spécifique Docker, base de données, etc.). + +--- + +# 10. Priorisation suggérée + +1. **Stabiliser MVP** (Phase 1 + tests fichier 09) +2. UX de base + tri / filtre (Phase 2) +3. Graphes d’historique (Phase 3) +4. Détection régressions + petites alertes (Phase 4) +5. Intégrations Home Assistant / Prometheus (Phase 5) +6. Support multi-OS (Phase 6) +7. Développements avancés (Phase 7+8) + +--- + +# 11. TODO résumé par phase + +- Phase 1 : + - Implémenter API, DB, bench.sh, WebUI minimal, Docker, install.sh +- Phase 2 : + - Tri, filtres, ergonomie +- Phase 3 : + - Graphes (global_score, composantes) +- Phase 4 : + - Baselines, détection de régression, marquage visuel +- Phase 5 : + - Webhooks / MQTT / intégration HA +- Phase 6 : + - Scripts bench pour autres OS +- Phase 7 : + - Vues avancées, cartes réseau, plugins + +Ce document pourra servir de base à un Kanban (Gitea, Kanboard, etc.) en créant une tâche par élément de la roadmap.