addon

2026-01-05 16:08:01 +01:00
parent dcba044cd6
commit c67befc549
2215 changed files with 26743 additions and 329 deletions
--- a/docs/FEATURE_USB_STRUCTURED_IMPORT.md
+++ b/docs/FEATURE_USB_STRUCTURED_IMPORT.md
@@ -0,0 +1,380 @@
+# 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)