ObsiGate/docs/features/drag-and-drop-ai.md

#89 — Drag & drop complet de fichiers / dossiers & intégration Assistant IA

Statut : ✅ Livré
Priorité : 🟡 P2
Zone : frontend + backend
Références : Roadmap · Assistant IA #80 · Assistant IA #88

---

🎯 Objectif

Offrir une expérience complète de glisser-déposer (Drag & Drop) dans ObsiGate couvrant à la fois la gestion de fichiers dans le vault et les interactions avec l'Assistant IA :

1. Glisser-déposer de fichiers individuels, multiples et dossiers récursifs depuis le système d'exploitation vers l'arborescence du vault.
2. Espace de drop dédié (dropzone explicite + overlay visuel réactif à double cible).
3. Glisser-déposer de fichiers / dossiers (internes au vault ou externes depuis l'OS) vers le panneau de l'assistant IA pour enrichir le contexte ou lui soumettre des instructions directes.

---

🏗️ Architecture & Composants

1. Backend — Endpoint d'upload récursif / batch (POST /api/vault/{vault}/batch-upload)

• Réception de structures de fichiers avec leurs chemins relatifs (relative_path).
• Validation de sécurité anti path-traversal via resolve_safe_path et validation d'extension via _validate_extension(allow_images=True).
• Création automatique et récursive des dossiers parents manquants.
• Gestion des collisions / écrasements (option d'écrasement avec sauvegarde automatique create_backup).
• Retour d'un bilan d'upload (uploaded, created_dirs, errors).

2. Frontend — Core Drag & Drop & Traversée d'arborescence (frontend/js/upload.js & dragdrop.js)

• Utilisation de la FileSystem API (DataTransferItem.webkitGetAsEntry()) pour extraire de manière récursive toute l'arborescence de répertoires et fichiers déposés depuis l'OS.
• Surbrillance dynamique des dossiers cibles dans l'arborescence (.tree-item) lors du survol d'éléments externes de type Files.
• Support du drop sur la racine d'un vault ou dans un sous-dossier spécifique.
• Feedback utilisateur immédiat via les toasts d'information / progression / succès.

3. Frontend — Dropzones dédiées & Overlay global

• Overlay visuel plein écran lors du drag d'éléments depuis l'OS sur l'application avec séparation claire des zones cibles :
  • Zone Vault : Déposer pour importer dans le dossier actif / vault.
  • Zone Assistant IA : Déposer pour analyser avec l'IA.
• Dropzone réactive dans le panneau BooksLM.

4. Intégration Assistant IA (frontend/js/bookslm.js)

• Drag interne (depuis l'arborescence ObsiGate vers le chat) :
  • Déposer un dossier : bascule l'assistant ou insère le dossier en contexte ad-hoc.
  • Déposer un ou plusieurs fichiers : ajoute les fichiers en context chips (_adhocFiles).
• Drag externe (depuis l'OS vers le chat) :
  • Images : ajout direct en pièce jointe pour les modèles multimodaux (vision).
  • Documents texte / Markdown / Code : lecture immédiate du contenu et ajout en contexte ad-hoc.

---

📋 Sous-tâches

• Backend :
  • Endpoint POST /api/vault/{vault}/batch-upload (gestion des sous-dossiers et upload en batch).
  • Services métier save_raw_file et batch_upload_files dans backend/services/mutations.py.
  • Tests unitaires backend (tests/test_batch_upload.py).
• Frontend Core Upload & Tree Drop :
  • Helper de lecture récursive readDataTransferEntries (fichiers + dossiers) dans frontend/js/upload.js.
  • Écouteurs dragover / drop sur l'arborescence du vault avec retour visuel dans frontend/js/dragdrop.js.
  • Gestion des transferts et notifications toasts.
• Overlay & Dropzone UI :
  • Détection globale du glisser externe sur la fenêtre avec overlay interactif (initGlobalDropOverlay).
  • Styles de l'overlay et des zones cibles dans frontend/style.css.
• Intégration Assistant IA :
  • Dropzone sur le composeur BooksLM (_setupDropZones).
  • Gestion des drops internes (fichiers/dossiers du vault) et externes (OS handleExternalDroppedItems).
  • Intégration transparente avec les chips de contexte et images multimodales.
• Internationalisation (i18n) :
  • Clés FR/EN pour toutes les indications de drop, progression et erreurs dans frontend/locales/{fr,en}.json.
• Tests & Validation :
  • Tests unitaires frontend tests/frontend/upload.test.mjs.
  • Validation de tous les imports/exports ES modules tests/frontend/validate-imports.mjs.