addon

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