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 :

{
  "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 :

# 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):

{
  "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):

{
  "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 :

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 :

<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 :

function showImportUSBStructuredModal() {
    document.getElementById('form-import-usb-structured').reset();
    document.getElementById('modal-import-usb-structured').style.display = 'block';
}

Ligne 501-583 - Fonction d'import :

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)