serv_benchmark/docs/IMPORT_MARKDOWN.md

# Import de périphériques depuis fichiers Markdown

Le module périphériques permet d'importer automatiquement des spécifications de périphériques depuis des fichiers Markdown (.md).

## Formats supportés

Le parser supporte deux formats de fichiers .md :

### Format simple

Le format minimal avec juste un titre et une description :

```markdown
# USB Device ID 0b05_17cb

## Description
Broadcom BCM20702A0 – Bluetooth USB (ASUS)
```

**Extraction automatique :**
- Nom du périphérique depuis la description
- Vendor ID et Product ID depuis le titre ou le nom de fichier
- Type de périphérique déduit de la description (souris, clavier, WiFi, etc.)
- Marque extraite de la description

### Format détaillé

Le format complet avec toutes les spécifications USB :

```markdown
# USB Device Specification — ID 0781:55ab

## Identification
- **Vendor ID**: 0x0781 (SanDisk Corp.)
- **Product ID**: 0x55ab
- **Commercial name**: SanDisk 3.2 Gen1 USB Flash Drive
- **Manufacturer string**: USB
- **Product string**: SanDisk 3.2Gen1
- **Serial number**: 040123d47e7a47e4ac9e89dd25318ac819d7be0fe18a9961190fdffe1052426fd4ae00000000000000000000a8e587bdff867418ab55810792a96c46

## USB Characteristics
- **USB version**: USB 3.2 Gen 1 (SuperSpeed)
- **Negotiated speed**: 5 Gb/s
- **bcdUSB**: 3.20
- **Max packet size (EP0)**: 9 bytes
- **Power mode**: Bus-powered
- **Max power draw**: 896 mA

## Device Class
- **Interface class**: 08 — Mass Storage
- **Subclass**: 06 — SCSI transparent command set
- **Protocol**: 80 — Bulk-Only Transport (BOT)

## Functional Role
- USB flash storage device
- Removable mass storage
- No HID or radio functionality

## Classification Summary
**Category**: USB Mass Storage Device
**Subcategory**: USB 3.x Flash Drive
**Criticality**: Low (non real-time device)
```

**Extraction complète :**
- Vendor ID et Product ID
- Nom commercial et modèle
- Marque (manufacturer)
- Numéro de série
- Version USB
- Vitesse de connexion
- Classe USB, sous-classe et protocole
- Catégorie fonctionnelle
- Notes sur le rôle, la performance, etc.

## Nommage des fichiers

Le parser peut extraire les IDs USB depuis le nom de fichier :

- `ID_0781_55ab.md` → Vendor: 0x0781, Product: 0x55ab
- `id_0b05_17cb.md` → Vendor: 0x0b05, Product: 0x17cb
- `ID_046d_c52b.md` → Vendor: 0x046d, Product: 0x c52b

## Détection automatique du type

Le parser détecte automatiquement le type de périphérique depuis la description :

| Mots-clés détectés | Type assigné |
|-------------------|--------------|
| souris, mouse | USB / Souris |
| clavier, keyboard | USB / Clavier |
| wifi, wireless | WiFi / Adaptateur WiFi |
| bluetooth | Bluetooth / Adaptateur Bluetooth |
| usb flash, clé usb, flash drive | USB / Clé USB |
| dongle | USB / Dongle |

## Extraction de la marque

Les marques courantes sont détectées automatiquement :
- Logitech
- SanDisk
- Ralink
- Broadcom
- ASUS
- Realtek
- TP-Link
- Intel
- Samsung
- Kingston
- Corsair

## Utilisation

### Via l'interface web

1. Accédez à [http://localhost:8087/peripherals.html](http://localhost:8087/peripherals.html)
2. Cliquez sur "Importer .md"
3. Sélectionnez votre fichier .md
4. Cliquez sur "Importer"
5. Le formulaire d'ajout s'ouvre avec les données pré-remplies
6. Vérifiez et complétez les informations
7. Enregistrez

### Via l'API

```bash
curl -X POST http://localhost:8007/api/peripherals/import/markdown \
  -F "file=@/path/to/ID_0781_55ab.md"
```

**Réponse :**

```json
{
  "success": true,
  "filename": "ID_0781_55ab.md",
  "parsed_data": {
    "nom": "SanDisk 3.2 Gen1 USB Flash Drive",
    "type_principal": "USB",
    "sous_type": "Clé USB",
    "marque": "SanDisk",
    "modele": "3.2Gen1",
    "numero_serie": "040123d47e7a...",
    "description": "SanDisk Corp. SanDisk 3.2Gen1",
    "caracteristiques_specifiques": {
      "vendor_id": "0x0781",
      "product_id": "0x55ab",
      "usb_version": "USB 3.2 Gen 1 (SuperSpeed)",
      "usb_speed": "5 Gb/s",
      "bcdUSB": "3.20",
      "max_power": "896 mA",
      "interface_class": "08",
      "interface_class_name": "Mass Storage",
      "category": "USB Mass Storage Device",
      "subcategory": "USB 3.x Flash Drive"
    }
  },
  "suggested_peripheral": {
    "nom": "SanDisk 3.2 Gen1 USB Flash Drive",
    "type_principal": "USB",
    "sous_type": "Clé USB",
    "marque": "SanDisk",
    "modele": "3.2Gen1",
    "numero_serie": "040123d47e7a...",
    "description": "SanDisk Corp. SanDisk 3.2Gen1",
    "caracteristiques_specifiques": { ... },
    "etat": "Neuf",
    "quantite_totale": 1,
    "quantite_disponible": 1
  }
}
```

## Sections reconnues

Le parser reconnaît les sections markdown suivantes :

- `## Description` - Description générale du périphérique
- `## Identification` - Vendor/Product ID, nom commercial, marque, modèle, S/N
- `## USB Characteristics` - Version USB, vitesse, alimentation
- `## Device Class` - Classe, sous-classe, protocole USB
- `## Functional Role` - Rôle fonctionnel (ajouté aux notes)
- `## Performance Notes` - Notes de performance
- `## Power & Stability Considerations` - Recommandations d'alimentation
- `## Recommended USB Port Placement` - Emplacement recommandé
- `## Typical Use Cases` - Cas d'usage typiques
- `## Operating System Support` - Support OS
- `## Classification Summary` - Catégorie et sous-catégorie

Les sections non listées ci-dessus sont ignorées.

## Caractéristiques spécifiques

Les informations USB techniques sont stockées dans le champ JSON `caracteristiques_specifiques` :

```json
{
  "vendor_id": "0x0781",
  "product_id": "0x55ab",
  "usb_version": "USB 3.2 Gen 1",
  "usb_speed": "5 Gb/s",
  "bcdUSB": "3.20",
  "max_power": "896 mA",
  "interface_class": "08",
  "interface_class_name": "Mass Storage",
  "interface_subclass": "06",
  "interface_subclass_name": "SCSI transparent command set",
  "interface_protocol": "80",
  "interface_protocol_name": "Bulk-Only Transport (BOT)",
  "category": "USB Mass Storage Device",
  "subcategory": "USB 3.x Flash Drive"
}
```

## Exemple de workflow complet

### 1. Créer un fichier de spécification

Créez `ID_046d_c52b.md` :

```markdown
# USB Device ID 046d_c52b

## Description
Logitech Unifying Receiver – Dongle clavier/souris
```

### 2. Importer via l'API

```bash
curl -X POST http://localhost:8007/api/peripherals/import/markdown \
  -F "file=@ID_046d_c52b.md"
```

### 3. Le backend analyse et retourne

```json
{
  "success": true,
  "filename": "ID_046d_c52b.md",
  "suggested_peripheral": {
    "nom": "Logitech Unifying Receiver – Dongle clavier/souris",
    "type_principal": "USB",
    "sous_type": "Dongle",
    "marque": "Logitech",
    "caracteristiques_specifiques": {
      "vendor_id": "0x046d",
      "product_id": "0xc52b"
    },
    "etat": "Neuf",
    "quantite_totale": 1,
    "quantite_disponible": 1
  }
}
```

### 4. Frontend pré-remplit le formulaire

L'utilisateur vérifie et complète :
- Prix d'achat
- Emplacement
- Photos
- Rating

### 5. Sauvegarde dans la base de données

Le périphérique est créé avec toutes les informations extraites.

## Gestion des erreurs

### Fichier non .md

```json
{
  "detail": "Only markdown (.md) files are supported"
}
```

### Encodage invalide

```json
{
  "detail": "File encoding error. Please ensure the file is UTF-8 encoded."
}
```

### Format invalide

```json
{
  "detail": "Failed to parse markdown file: ..."
}
```

## Fichiers d'exemple

Des fichiers d'exemple se trouvent dans le dossier `fichier_usb/` :

```bash
ls fichier_usb/
ID_0781_55ab.md      # Format détaillé
ID_0b05_17cb.md      # Format simple
ID_046d_c52b.md      # Logitech dongle
ID_148f_7601.md      # Adaptateur WiFi
...
```

## Code source

- **Parser backend** : [backend/app/utils/md_parser.py](../backend/app/utils/md_parser.py)
- **Endpoint API** : [backend/app/api/endpoints/peripherals.py](../backend/app/api/endpoints/peripherals.py)
- **Frontend modal** : [frontend/peripherals.html](../frontend/peripherals.html)
- **JavaScript handler** : [frontend/js/peripherals.js](../frontend/js/peripherals.js)

---

**Note :** Cette fonctionnalité complète l'import USB (`lsusb -v`) pour permettre l'import de spécifications pré-formatées en markdown.