# 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