serv_benchmark/FEATURE_IMPORT_MD.md

Nouvelle fonctionnalité : Import de fichiers .md

Résumé

Un nouveau bouton "Importer .md" a été ajouté au module Périphériques pour permettre l'import automatique de spécifications de périphériques depuis des fichiers Markdown.

Fichiers créés/modifiés

Backend

Nouveau :

• backend/app/utils/md_parser.py - Parser markdown (300+ lignes)

Modifié :

• backend/app/api/endpoints/peripherals.py - Ajout endpoint /api/peripherals/import/markdown

Frontend

Modifié :

• frontend/peripherals.html - Nouveau bouton + modal import .md
• frontend/js/peripherals.js - Fonctions showImportMDModal() et importMarkdown()
• frontend/css/peripherals.css - Styles pour la preview de fichier

Documentation

Créé :

• docs/IMPORT_MARKDOWN.md - Guide complet d'utilisation

Modifié :

• MODULE_PERIPHERIQUES_RESUME.md - Ajout de la fonctionnalité
• CHANGELOG.md - Mise à jour avec import .md

Utilisation rapide

1. Interface web

1. Ouvrir http://localhost:8087/peripherals.html
2. Cliquer sur "Importer .md"
3. Sélectionner un fichier .md (ex: fichier_usb/ID_0781_55ab.md)
4. Cliquer sur "Importer"
5. Le formulaire se pré-remplit automatiquement
6. Compléter et enregistrer

2. API directe

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

Formats supportés

Format simple (minimal)

# USB Device ID 0b05_17cb

## Description
Broadcom BCM20702A0 – Bluetooth USB (ASUS)

Extraction automatique :

• Vendor ID et Product ID depuis le titre/nom de fichier
• Nom du périphérique depuis la description
• Type déduit (Bluetooth)
• Marque extraite (ASUS)

Format détaillé (complet)

# USB Device Specification — ID 0781:55ab

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

## USB Characteristics
- **USB version**: USB 3.2 Gen 1
- **Negotiated speed**: 5 Gb/s
- **Max power draw**: 896 mA

## Device Class
- **Interface class**: 08 — Mass Storage
- **Subclass**: 06 — SCSI transparent command set

## Classification Summary
**Category**: USB Mass Storage Device
**Subcategory**: USB 3.x Flash Drive

Extraction complète :

• Tous les champs du format simple
• Numéro de série
• Caractéristiques USB (version, vitesse, alimentation)
• Classe USB et protocole
• Catégorie fonctionnelle
• Notes sur rôle, performance, etc.

Tests

Fichiers de test disponibles

Dans le dossier fichier_usb/ :

# Format simple
fichier_usb/ID_0b05_17cb.md    # Bluetooth ASUS
fichier_usb/ID_046d_c52b.md    # Logitech Unifying
fichier_usb/ID_148f_7601.md    # Adaptateur WiFi

# Format détaillé
fichier_usb/id_0781_55_ab.md   # SanDisk USB 3.2 (2079 lignes)

Test rapide

Via interface :

# 1. Démarrer l'application
docker compose up -d

# 2. Ouvrir navigateur
http://localhost:8087/peripherals.html

# 3. Tester import
- Cliquer "Importer .md"
- Sélectionner fichier_usb/ID_0b05_17cb.md
- Vérifier pré-remplissage du formulaire

Via API :

# Test import simple
curl -X POST http://localhost:8007/api/peripherals/import/markdown \
  -F "file=@fichier_usb/ID_0b05_17cb.md" | jq

# Test import détaillé
curl -X POST http://localhost:8007/api/peripherals/import/markdown \
  -F "file=@fichier_usb/id_0781_55_ab.md" | jq

Détection automatique

Le parser détecte automatiquement :

Dans la description	Type assigné	Sous-type
souris, mouse	USB	Souris
clavier, keyboard	USB	Clavier
wifi, wireless	WiFi	Adaptateur WiFi
bluetooth	Bluetooth	Adaptateur Bluetooth
usb flash, clé usb	USB	Clé USB
dongle	USB	Dongle

Marques détectées : Logitech, SanDisk, Ralink, Broadcom, ASUS, Realtek, TP-Link, Intel, Samsung, Kingston, Corsair

Données extraites

Champs de base

• nom - Nom commercial ou description
• type_principal - Type (USB, Bluetooth, WiFi...)
• sous_type - Sous-type (Souris, Clavier, Clé USB...)
• marque - Marque du fabricant
• modele - Modèle
• numero_serie - Numéro de série
• description - Description complète
• notes - Notes techniques et recommandations

Caractéristiques spécifiques (JSON)

Stockées dans caracteristiques_specifiques :

{
  "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",
  "category": "USB Mass Storage Device",
  "subcategory": "USB 3.x Flash Drive"
}

Gestion d'erreurs

Erreur	Code	Message
Fichier non .md	400	Only markdown (.md) files are supported
Encodage invalide	400	File encoding error. Please ensure the file is UTF-8 encoded
Format invalide	400	Failed to parse markdown file: ...

Workflow complet

Cas 1 : Périphérique nouveau (n'existe pas)

1. Utilisateur : Clique "Importer .md"
2. Frontend : Affiche modal avec file input
3. Utilisateur : Sélectionne fichier .md
4. Frontend : Affiche preview (nom + taille)
5. Utilisateur : Clique "Importer"
6. Frontend : Envoie FormData à /api/peripherals/import/markdown
7. Backend : Parse le markdown avec md_parser.py
8. Backend : Extrait vendor_id, product_id, nom, marque, etc.
9. Backend : Vérifie si existe déjà (vendor_id + product_id)
10. Backend : Retourne JSON avec already_exists=false + suggested_peripheral
11. Frontend : Ferme modal import
12. Frontend : Ouvre modal ajout avec formulaire
13. Frontend : Pré-remplit tous les champs du formulaire
14. Utilisateur : Vérifie, complète (prix, localisation, photos)
15. Utilisateur : Enregistre
16. Frontend : POST /api/peripherals
17. Backend : Crée le périphérique dans peripherals.db
18. Frontend : Affiche succès et recharge la liste

Cas 2 : Périphérique déjà existant (doublon détecté)

1. Utilisateur : Clique "Importer .md"
2. Frontend : Affiche modal avec file input
3. Utilisateur : Sélectionne fichier .md (ex: ID_0781_55ab.md)
4. Frontend : Affiche preview (nom + taille)
5. Utilisateur : Clique "Importer"
6. Frontend : Envoie FormData à /api/peripherals/import/markdown
7. Backend : Parse le markdown avec md_parser.py
8. Backend : Extrait vendor_id=0x0781, product_id=0x55ab
9. Backend : Vérifie si existe déjà → TROUVÉ !
10. Backend : Retourne JSON avec already_exists=true + existing_peripheral
11. Frontend : Ferme modal import
12. Frontend : Affiche dialog de confirmation :
    "Ce périphérique existe déjà dans la base de données:
     Nom: SanDisk USB Flash Drive
     Marque: SanDisk
     Modèle: 3.2Gen1
     Quantité: 2

     Voulez-vous voir ce périphérique?"

13a. Si OUI : Redirige vers peripheral-detail.html?id=X
13b. Si NON : Affiche message "Import annulé - le périphérique existe déjà"

Intégration avec import USB

Le module propose maintenant deux méthodes d'import :

Import USB (lsusb -v)

• ✅ Pour périphériques actuellement connectés
• ✅ Données en temps réel du système
• ✅ Détection automatique de tous les détails USB

Import Markdown (.md)

• ✅ Pour périphériques déconnectés ou stockés
• ✅ Spécifications pré-documentées
• ✅ Import en lot de fiches techniques
• ✅ Détection de doublons (vendor_id + product_id)
• ✅ Historique et documentation

API Endpoint

POST /api/peripherals/import/markdown
Content-Type: multipart/form-data

Parameters:
  file: UploadFile (required) - Fichier .md

Response 200 (nouveau périphérique):
{
  "success": true,
  "already_exists": false,
  "filename": "ID_0781_55ab.md",
  "parsed_data": { ... },
  "suggested_peripheral": {
    "nom": "...",
    "type_principal": "...",
    ...
  }
}

Response 200 (périphérique existant):
{
  "success": true,
  "already_exists": true,
  "existing_peripheral_id": 42,
  "existing_peripheral": {
    "id": 42,
    "nom": "SanDisk USB Flash Drive",
    "type_principal": "USB",
    "marque": "SanDisk",
    "modele": "3.2Gen1",
    "quantite_totale": 2,
    "quantite_disponible": 1
  },
  "filename": "ID_0781_55ab.md",
  "message": "Un périphérique avec vendor_id=0x0781 et product_id=0x55ab existe déjà"
}

Response 400:
{
  "detail": "Error message"
}

Fichiers source

Fichier	Lignes	Description
backend/app/utils/md_parser.py	~300	Parser markdown principal
backend/app/api/endpoints/peripherals.py	+70	Endpoint API
frontend/peripherals.html	+30	Modal HTML
frontend/js/peripherals.js	+75	Handler JavaScript
frontend/css/peripherals.css	+30	Styles preview
docs/IMPORT_MARKDOWN.md	~400	Documentation complète

Total : ~900 lignes de code ajoutées

Documentation

Pour plus de détails, voir :

• Guide complet : docs/IMPORT_MARKDOWN.md
• Spécifications : MODULE_PERIPHERIQUES_RESUME.md
• Changelog : CHANGELOG.md

---

Développé avec Claude Code - 2025-12-30