addon
This commit is contained in:
Gilles Soulier
395
README_PERIPHERALS.md
Executable file
395
README_PERIPHERALS.md
Executable file
@@ -0,0 +1,395 @@
|
||||
# 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](frontend/peripherals.html:1))
|
||||
- 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](frontend/peripheral-detail.html:1))
|
||||
- Informations complètes
|
||||
- Gestion photos
|
||||
- Gestion documents
|
||||
- Gestion liens
|
||||
- Historique
|
||||
- Notes
|
||||
|
||||
✅ **Thème Monokai complet** ([frontend/css/monokai.css](frontend/css/monokai.css:1))
|
||||
- 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
|
||||
|
||||
```bash
|
||||
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](backend/app/core/config.py:1).
|
||||
|
||||
Variables d'environnement disponibles :
|
||||
```bash
|
||||
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
|
||||
|
||||
```bash
|
||||
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
|
||||
|
||||
```bash
|
||||
# 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](config/peripheral_types.yaml:1) :
|
||||
|
||||
```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](config/locations.yaml:1)
|
||||
|
||||
### Ajuster la compression d'images
|
||||
|
||||
Éditer [config/image_processing.yaml](config/image_processing.yaml:1) :
|
||||
|
||||
```yaml
|
||||
image_processing:
|
||||
compression:
|
||||
quality: 85 # 1-100
|
||||
format: webp
|
||||
thumbnail:
|
||||
size: 300
|
||||
quality: 75
|
||||
```
|
||||
|
||||
## 🔧 Développement
|
||||
|
||||
### Lancer le backend en mode dev
|
||||
|
||||
```bash
|
||||
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
|
||||
|
||||
```bash
|
||||
# 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
|
||||
Reference in New Issue
Block a user