serv_benchmark/README_PERIPHERALS.md

Module Périphériques - Linux BenchTools

Module complet de gestion d'inventaire de périphériques pour Linux BenchTools.

✅ Statut d'implémentation

Phase 1 Backend : 100% COMPLÉTÉ Phase 2 Frontend : 80% COMPLÉTÉ (pages principales + détails)

📋 Fonctionnalités implémentées

Backend (100%)

✅ Base de données séparée (peripherals.db)

• 7 tables SQLAlchemy
• Sessions DB dédiées
• Migrations automatiques

✅ 30+ types de périphériques configurables (YAML)

• USB (clavier, souris, hub, webcam, stockage)
• Bluetooth (clavier, souris, audio)
• Réseau (Wi-Fi, Ethernet)
• Stockage (SSD, HDD, clé USB)
• Video (GPU, écran, webcam)
• Audio (haut-parleur, microphone, casque)
• Câbles (USB, HDMI, DisplayPort, Ethernet)
• Consoles (PlayStation, Xbox, Nintendo)
• Microcontrôleurs (Raspberry Pi, Arduino, ESP32)
• Quincaillerie (vis, écrous, entretoises)

✅ CRUD complet

• Périphériques
• Localisations hiérarchiques
• Prêts
• Photos
• Documents
• Liens

✅ Upload et gestion de fichiers

• Compression automatique WebP (85% qualité)
• Génération de thumbnails (300x300)
• Support images et documents

✅ Import USB automatique

• Parser pour sudo lsusb -v
• Détection automatique vendor/product ID
• Pré-remplissage des formulaires

✅ Système de prêts

• Gestion complète des emprunts
• Rappels automatiques (7j avant retour)
• Prêts en retard
• Historique complet

✅ Localisations hiérarchiques

• Arborescence complète (bâtiment > étage > pièce > placard > tiroir > boîte)
• Génération de QR codes
• Photos de localisation
• Comptage récursif

✅ Historique et traçabilité

• Tous les mouvements trackés
• Assignations aux devices
• Modifications d'état

✅ Statistiques

• Total périphériques
• Disponibles vs en prêt
• Stock faible
• Par type
• Par état

✅ API REST complète (20+ endpoints)

Frontend (80%)

✅ Page principale périphériques (frontend/peripherals.html)

• Liste paginée (50 items/page)
• Recherche full-text
• Filtres multiples (type, localisation, état)
• Tri sur toutes les colonnes
• Stats en temps réel
• Modal d'ajout
• Modal import USB

✅ Page détail périphérique (frontend/peripheral-detail.html)

• Informations complètes
• Gestion photos
• Gestion documents
• Gestion liens
• Historique
• Notes

✅ Thème Monokai complet (frontend/css/monokai.css)

• CSS variables
• Dark theme professionnel
• Responsive design
• Animations fluides

📁 Structure des fichiers

backend/
├── app/
│   ├── api/endpoints/
│   │   ├── peripherals.py      # 20+ endpoints périphériques
│   │   └── locations.py         # Endpoints localisations
│   ├── models/
│   │   ├── peripheral.py        # 5 modèles (Peripheral, Photo, Doc, Link, Loan)
│   │   ├── location.py          # Modèle Location
│   │   └── peripheral_history.py
│   ├── schemas/
│   │   └── peripheral.py        # Schémas Pydantic (400+ lignes)
│   ├── services/
│   │   └── peripheral_service.py # Logique métier
│   ├── utils/
│   │   ├── usb_parser.py        # Parser lsusb -v
│   │   ├── image_processor.py   # Compression WebP
│   │   ├── qr_generator.py      # QR codes
│   │   └── yaml_loader.py       # Chargeur YAML
│   ├── core/
│   │   └── config.py            # Config périphériques
│   └── db/
│       ├── session.py           # 2 sessions DB
│       └── init_db.py           # Init périphériques DB

config/
├── peripheral_types.yaml        # 30+ types configurables
├── locations.yaml               # Types de localisations
├── image_processing.yaml        # Config compression
└── notifications.yaml           # Config rappels

frontend/
├── peripherals.html             # Page principale
├── peripheral-detail.html       # Page détail
├── css/
│   ├── monokai.css             # Thème global
│   └── peripherals.css         # Styles spécifiques
└── js/
    ├── peripherals.js          # Logique liste
    ├── peripheral-detail.js    # Logique détail
    └── utils.js                # Fonctions utilitaires (augmenté)

🚀 Installation

1. Installer les dépendances Python

cd backend
pip install -r requirements.txt

Nouvelles dépendances ajoutées :

• Pillow==10.2.0 - Traitement d'images
• qrcode[pil]==7.4.2 - Génération QR codes
• PyYAML==6.0.1 - Chargement YAML

2. Configuration

Le module est activé par défaut via PERIPHERALS_MODULE_ENABLED=true dans backend/app/core/config.py.

Variables d'environnement disponibles :

PERIPHERALS_DB_URL=sqlite:///./backend/data/peripherals.db
PERIPHERALS_MODULE_ENABLED=true
PERIPHERALS_UPLOAD_DIR=./uploads/peripherals
IMAGE_COMPRESSION_ENABLED=true
IMAGE_COMPRESSION_QUALITY=85

3. Initialisation de la base de données

cd backend
python -m app.main

La base de données peripherals.db sera créée automatiquement avec :

• 7 tables
• Dossiers d'upload
• Répertoires pour photos/documents/QR codes

📚 Utilisation

API Backend

Le backend démarre sur http://localhost:8007

Endpoints principaux

Périphériques :

• POST /api/peripherals - Créer
• GET /api/peripherals - Lister (avec pagination, filtres, recherche)
• GET /api/peripherals/{id} - Détails
• PUT /api/peripherals/{id} - Modifier
• DELETE /api/peripherals/{id} - Supprimer
• GET /api/peripherals/statistics/summary - Statistiques

Photos :

• POST /api/peripherals/{id}/photos - Upload photo (multipart/form-data)
• GET /api/peripherals/{id}/photos - Liste photos
• DELETE /api/peripherals/photos/{photo_id} - Supprimer

Documents :

• POST /api/peripherals/{id}/documents - Upload document
• GET /api/peripherals/{id}/documents - Liste documents
• DELETE /api/peripherals/documents/{doc_id} - Supprimer

Liens :

• POST /api/peripherals/{id}/links - Ajouter lien
• GET /api/peripherals/{id}/links - Liste liens
• DELETE /api/peripherals/links/{link_id} - Supprimer

Prêts :

• POST /api/peripherals/loans - Créer prêt
• POST /api/peripherals/loans/{id}/return - Retourner
• GET /api/peripherals/loans/overdue - Prêts en retard
• GET /api/peripherals/loans/upcoming?days=7 - Prêts à venir

Localisations :

• POST /api/locations - Créer
• GET /api/locations - Lister
• GET /api/locations/tree - Arborescence complète
• GET /api/locations/{id}/path - Chemin complet
• POST /api/locations/{id}/qr-code - Générer QR code

Import USB :

• POST /api/peripherals/import/usb - Parser sortie sudo lsusb -v

Exemple de requête

# Créer un périphérique
curl -X POST http://localhost:8007/api/peripherals \
  -H "Content-Type: application/json" \
  -d '{
    "nom": "Logitech MX Master 3",
    "type_principal": "USB",
    "sous_type": "Souris",
    "marque": "Logitech",
    "modele": "MX Master 3",
    "prix": 99.99,
    "etat": "Neuf",
    "rating": 5.0
  }'

# Importer depuis lsusb
sudo lsusb -v > /tmp/usb_output.txt
curl -X POST http://localhost:8007/api/peripherals/import/usb \
  -F "lsusb_output=@/tmp/usb_output.txt"

Frontend

Ouvrir dans le navigateur :

• Liste : http://localhost:8000/peripherals.html
• Détail : http://localhost:8000/peripheral-detail.html?id=1

🎨 Personnalisation

Ajouter un nouveau type de périphérique

Éditer config/peripheral_types.yaml :

peripheral_types:
  - id: mon_nouveau_type
    nom: Mon Nouveau Type
    type_principal: Catégorie
    sous_type: Sous-catégorie
    icone: icon-name
    caracteristiques_specifiques:
      - nom: champ1
        label: Label du champ
        type: text|number|select|boolean
        options: [Option1, Option2]  # Si type=select
        requis: true|false

Modifier les types de localisations

Éditer config/locations.yaml

Ajuster la compression d'images

Éditer config/image_processing.yaml :

image_processing:
  compression:
    quality: 85  # 1-100
    format: webp
  thumbnail:
    size: 300
    quality: 75

🔧 Développement

Lancer le backend en mode dev

cd backend
uvicorn app.main:app --reload --port 8007

Structure de la base de données

Table peripherals (60+ colonnes) :

• Identification (nom, type, marque, modèle, SN...)
• Achat (boutique, date, prix, garantie...)
• Stock (quantités, seuil alerte)
• Localisation physique
• Linux (device_path, vendor_id, product_id...)
• Installation (drivers, firmware, paquets...)
• Appareil complet (lien vers devices.id)
• Caractéristiques spécifiques (JSON)

Tables liées :

• peripheral_photos - Photos avec primary flag
• peripheral_documents - Documents (manuel, garantie, facture...)
• peripheral_links - Liens externes
• peripheral_loans - Prêts/emprunts
• locations - Localisations hiérarchiques
• peripheral_location_history - Historique mouvements

Cross-database queries

Le système utilise deux bases de données séparées :

• data.db - Benchmarks et devices
• peripherals.db - Périphériques

Les liens entre les deux sont gérés via foreign keys logiques (integers) sans contraintes SQL FK, permettant :

• Assignation de périphériques à des devices (peripheral.device_id → devices.id)
• Liaison d'appareils complets aux benchmarks (peripheral.linked_device_id → devices.id)

📊 Tests

Test manuel rapide

# 1. Démarrer le backend
cd backend && python -m app.main

# 2. Créer un périphérique test
curl -X POST http://localhost:8007/api/peripherals \
  -H "Content-Type: application/json" \
  -d '{"nom":"Test Device","type_principal":"USB","sous_type":"Autre"}'

# 3. Lister
curl http://localhost:8007/api/peripherals

# 4. Stats
curl http://localhost:8007/api/peripherals/statistics/summary

🐛 Dépannage

La base de données n'est pas créée

Vérifier que PERIPHERALS_MODULE_ENABLED=true et relancer l'application.

Les images ne s'uploadent pas

Vérifier les permissions sur ./uploads/peripherals/

L'import USB ne fonctionne pas

S'assurer que la sortie est bien celle de sudo lsusb -v (pas juste lsusb)

📝 TODO / Améliorations futures

• Pages localisations et prêts dans le frontend
• Mode édition in-place pour les périphériques
• Scan de QR codes avec caméra
• Export Excel/CSV de l'inventaire
• Graphiques et statistiques avancées
• Notifications email pour rappels de prêts
• API de recherche avancée avec filtres combinés
• Import en masse depuis CSV
• Détection automatique périphériques USB connectés
• Intégration avec système de tickets/GLPI

📄 Licence

Même licence que Linux BenchTools

👥 Contribution

Développé avec Claude Code (Anthropic)

---

Dernière mise à jour : 2025-12-30