serv_benchmark/docs/FEATURE_USB_STRUCTURED_IMPORT.md

# Feature: Import USB avec informations structurées

## Vue d'ensemble

Import de périphériques USB à partir d'informations structurées (format texte avec champs identifiés).
Contrairement à l'import `lsusb -v` qui nécessite la sortie brute de la commande, cet import accepte des informations formatées provenant d'outils GUI ou de sorties pré-traitées.

## Format d'entrée supporté

### Format texte structuré (français)

```
Bus : 003
Device : 040
Vendor ID : 0x2b89
Product ID : 0x8761
Vendor string : Realtek
Product string : Bluetooth Radio
Numéro de série : 00E04C239987
Vitesse négociée : Full Speed (12 Mbps)
Version USB déclarée : USB 1.10 (bcdUSB 1.10)
Classe périphérique : 224 → Wireless
Sous-classe périphérique : 1 → Radio Frequency
Protocole périphérique : 1 → Bluetooth
Puissance maximale déclarée : 500 mA
Mode d'alimentation : Self Powered
Interface 0
Classe interface : 224 → Wireless
...
```

## Avantages par rapport à lsusb -v

| Aspect | lsusb -v | Info structurée |
|--------|----------|-----------------|
| **Format** | Sortie brute complète | Informations sélectionnées |
| **Source** | Commande CLI uniquement | CLI, GUI, outils tiers |
| **Taille** | Très volumineuse | Plus compacte |
| **Lisibilité** | Difficile (sortie brute) | Facile (formaté) |
| **Stockage CLI** | Markdown brut | **YAML structuré** |

## Workflow utilisateur

1. **Obtenir les informations USB** depuis :
   - Un outil GUI (gestionnaire de périphériques)
   - Une sortie formatée d'un script
   - Un export d'un autre système

2. **Cliquer sur "Importer USB (Info)"**

3. **Coller les informations** dans la zone de texte

4. **Cliquer "Importer"**

5. **Le système :**
   - ✅ Parse les informations
   - ✅ Extrait les champs généraux (nom, marque, numero_serie)
   - ✅ **Détecte automatiquement type_principal et sous_type**
   - ✅ Formate TOUTES les infos en **YAML structuré** pour le champ `cli`
   - ✅ Vérifie si le périphérique existe déjà
   - ✅ Pré-remplit le formulaire

6. **Utilisateur complète et enregistre**

## Extraction des champs

### Champs généraux (formulaire)

Extraits automatiquement :
- **`nom`** ← `Product string` ou `iProduct`
- **`marque`** ← `Vendor string` ou `iManufacturer`
- **`numero_serie`** ← `Numéro de série` (si présent)

### Caractéristiques spécifiques (JSON)

Pour recherche et filtrage :
```json
{
  "vendor_id": "0x2b89",
  "product_id": "0x8761",
  "usb_version": "USB 1.10",
  "vitesse_negociee": "Full Speed (12 Mbps)",
  "device_class": "224",
  "device_class_nom": "Wireless",
  "device_subclass": "1",
  "device_subclass_nom": "Radio Frequency",
  "device_protocol": "1",
  "device_protocol_nom": "Bluetooth",
  "max_power": "500 mA",
  "power_mode": "Self Powered"
}
```

### Section CLI (YAML structuré)

**TOUTES** les informations en format YAML pour une vue complète :

```yaml
# Informations USB extraites

bus: '003'
device: '040'

identification:
  vendor_id: '0x2b89'
  product_id: '0x8761'
  vendor_string: Realtek
  product_string: Bluetooth Radio
  numero_serie: 00E04C239987

usb:
  version: USB 1.10
  vitesse_negociee: Full Speed (12 Mbps)

classe:
  device_class: '224'
  device_class_nom: Wireless
  device_subclass: '1'
  device_subclass_nom: Radio Frequency
  device_protocol: '1'
  device_protocol_nom: Bluetooth

alimentation:
  max_power: 500 mA
  power_mode: Self Powered

interfaces:
  - numero: 0
    classe:
      code: '224'
      nom: Wireless
    sous_classe:
      code: '1'
      nom: Radio Frequency
    protocole:
      code: '1'
      nom: Bluetooth
    nombre_endpoints: 3

endpoints:
  - adresse: '0x81'
    direction: IN
    type_transfert: Interrupt
    taille_max_paquet: 16
    intervalle: 1
  - adresse: '0x02'
    direction: OUT
    type_transfert: Bulk
    taille_max_paquet: 64
```

## Détection automatique du type

Le système utilise le même classificateur intelligent que l'import lsusb :

**Exemple 1 : Bluetooth**
```
Classe périphérique : 224 → Wireless
Protocole périphérique : 1 → Bluetooth
```
→ **Détecté : `type_principal = "Bluetooth"`, `sous_type = "Autre"`**

**Exemple 2 : Clé USB**
```
Classe périphérique : 0 [unknown]
Classe interface : 8 → Mass Storage
Product string : SanDisk 3.2Gen1
```
→ **Détecté : `type_principal = "Stockage"`, `sous_type = "Clé USB"`**

**Exemple 3 : Disque dur externe**
```
Classe interface : 8 → Mass Storage
Product string : My Passport 25A2
```
→ **Détecté : `type_principal = "Stockage"`, `sous_type = "Disque dur externe"`**

## API Endpoint

### POST /api/peripherals/import/usb-structured

**Request:**
```
POST /api/peripherals/import/usb-structured
Content-Type: multipart/form-data

usb_info: <texte formaté>
```

**Response (nouveau périphérique):**
```json
{
  "success": true,
  "already_exists": false,
  "suggested_peripheral": {
    "nom": "Bluetooth Radio",
    "marque": "Realtek",
    "numero_serie": "00E04C239987",
    "type_principal": "Bluetooth",
    "sous_type": "Autre",
    "cli": "# Informations USB\n\n## Données structurées (YAML)\n\n```yaml\n...\n```\n\n## Sortie brute\n\n```\n...\n```",
    "caracteristiques_specifiques": {
      "vendor_id": "0x2b89",
      "product_id": "0x8761",
      ...
    }
  },
  "parsed_data": {
    "bus": "003",
    "device": "040",
    ...
  }
}
```

**Response (périphérique existant):**
```json
{
  "success": true,
  "already_exists": true,
  "existing_peripheral_id": 42,
  "existing_peripheral": {
    "id": 42,
    "nom": "Bluetooth Radio",
    "marque": "Realtek",
    ...
  }
}
```

## Fichiers modifiés

### Backend

#### 1. Parser USB structuré - `backend/app/utils/usb_info_parser.py` (NOUVEAU)

Fonctions principales :
- `parse_structured_usb_info()` - Parse le texte structuré
- `extract_interfaces()` - Extrait les interfaces
- `extract_endpoints()` - Extrait les endpoints
- `format_cli_as_yaml()` - Formate en YAML
- `create_full_cli_section()` - Crée la section CLI complète (YAML + raw)

#### 2. API Endpoint - `backend/app/api/endpoints/peripherals.py`

**Ligne 29** - Import du parser :
```python
from app.utils.usb_info_parser import parse_structured_usb_info, create_full_cli_section
```

**Ligne 865-972** - Nouvel endpoint `/import/usb-structured` :
- Parse les informations structurées
- Classification intelligente du type
- Détection des doublons
- Retour des données suggérées avec CLI en YAML

### Frontend

#### 1. HTML - `frontend/peripherals.html`

**Ligne 67-69** - Nouveau bouton dans la toolbar :
```html
<button class="btn btn-secondary" onclick="showImportUSBStructuredModal()">
    <i class="fas fa-info-circle"></i> Importer USB (Info)
</button>
```

**Ligne 342-376** - Nouveau modal `modal-import-usb-structured` :
- Instructions
- Zone de texte grande (20 lignes)
- Placeholder avec exemple
- Boutons Annuler/Importer

#### 2. JavaScript - `frontend/js/peripherals.js`

**Ligne 310-314** - Fonction d'affichage du modal :
```javascript
function showImportUSBStructuredModal() {
    document.getElementById('form-import-usb-structured').reset();
    document.getElementById('modal-import-usb-structured').style.display = 'block';
}
```

**Ligne 501-583** - Fonction d'import :
```javascript
async function importUSBStructured(event) {
    // 1. Appel API
    // 2. Gestion doublon
    // 3. Pré-remplissage formulaire
    // 4. Pré-sélection type_principal et sous_type
}
```

## Exemples d'utilisation

### Exemple 1 : Import Bluetooth Realtek

**Input :**
```
Bus : 003
Device : 040
Vendor ID : 0x2b89
Product ID : 0x8761
Vendor string : Realtek
Product string : Bluetooth Radio
Numéro de série : 00E04C239987
Vitesse négociée : Full Speed (12 Mbps)
Version USB déclarée : USB 1.10 (bcdUSB 1.10)
Classe périphérique : 224 → Wireless
Sous-classe périphérique : 1 → Radio Frequency
Protocole périphérique : 1 → Bluetooth
Puissance maximale déclarée : 500 mA
Mode d'alimentation : Self Powered
```

**Résultat :**
- `nom` = "Bluetooth Radio"
- `marque` = "Realtek"
- `type_principal` = "Bluetooth" (détecté)
- `sous_type` = "Autre" (détecté)
- `cli` = YAML structuré + sortie brute

### Exemple 2 : Import Clé USB SanDisk

**Input :**
```
Bus : 004
Device : 005
Vendor ID : 0x0781
Product ID : 0x55ab
Vendor string : SanDisk Corp.
Product string : SanDisk 3.2Gen1
Vitesse négociée : SuperSpeed (5 Gbps)
Version USB déclarée : USB 3.20 (bcdUSB 3.20)
Classe périphérique : 0 [unknown]
Puissance maximale déclarée : 896 mA
Mode d'alimentation : Bus Powered
Interface 0
Classe interface : 8 → Mass Storage
Sous-classe interface : 6 → SCSI
Protocole interface : 80 → Bulk-Only
```

**Résultat :**
- `nom` = "SanDisk 3.2Gen1"
- `marque` = "SanDisk Corp."
- `type_principal` = "Stockage" (détecté via classe 8)
- `sous_type` = "Clé USB" (détecté via mots-clés)
- `cli` = YAML avec interfaces et endpoints

## Comparaison des 3 méthodes d'import

| Méthode | Source | Complexité | Format CLI | Cas d'usage |
|---------|--------|------------|------------|-------------|
| **lsusb -v** | Commande CLI | 2 étapes (sélection) | Markdown brut | Système Linux avec accès terminal |
| **Info structurée** | Texte formaté | 1 étape (direct) | **YAML + brut** | Outils GUI, exports, documentation |
| **Markdown (.md)** | Fichier | 1 étape (upload) | Stocké dans `synthese` | Spécifications existantes |

## Avantages de cette approche

✅ **Format YAML exploitable** - Facile à parser, requêter, afficher
✅ **Vue complète** - YAML structuré + sortie brute préservée
✅ **Détection automatique** - Type et sous-type détectés intelligemment
✅ **Flexible** - Accepte différentes sources d'information
✅ **Organisé** - Informations groupées logiquement (identification, USB, classe, alimentation, interfaces, endpoints)
✅ **Extensible** - Facile d'ajouter de nouveaux champs parsés

## Limitations

⚠️ **Format français uniquement** - Les patterns regex sont en français
⚠️ **Champs optionnels** - Si un champ manque, il n'apparaîtra pas dans le YAML
⚠️ **Numéro de série** - Peut être très long (hash pour certains périphériques)

## Améliorations futures

1. **Support multilingue** - Patterns en anglais + français
2. **Validation** - Vérifier la cohérence des données
3. **Templates** - Proposer des templates pour différents outils
4. **Export** - Générer le format structuré depuis une fiche existante
5. **Comparaison** - Comparer deux CLI YAML (avant/après)