Projets/ObsiGate
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 6 Wiki Activity
Files
c4b8e66206ab26219a356f8415b387c7d88c2356
ObsiGate/docs/GUIDES/RECHERCHE_PDF_EXCALIDRAW.md
T
bruno 472ea9d309
CI / lint (push) Successful in 2m24s
Details
CI / security (push) Failing after 1m39s
Details
CI / test (push) Successful in 4m0s
Details
CI / build (push) Successful in 1m37s
Details
CI / e2e (push) Successful in 15m34s
Details
feat: chargement à la demande des lignes cachées des tableurs #153 
A9bis : sous une feuille tronquée, un pied de page « N lignes affichées
sur M · Charger la suite » fetch la fenêtre suivante (limit=500) au clic
ou à l'approche du bas du tableau (sentinelle de défilement, marge 120px).
Les lignes ajoutées passent par le même pipeline d'édition que le rendu
initial (setupCell factorisé) : éditables et sauvegardables immédiatement.
Fetch échoué → bouton restauré (retry) + toast ; feuille complète → pied
de page masqué (class done).

Vérifié : xlsx-viewer.test.mjs 19/19 (5 nouveaux, contre-preuve
wireLazyRows désactivé → 5 échecs), E2E 8/8 (A520 visible et éditable
après clic), validate-imports 40 modules, unit.test.mjs 12/12, i18n parity.

🤖 Generated with Codebuff
Co-Authored-By: Codebuff <[email protected]>
2026-09-28 11:52:42 -04:00

9.8 KiB
Raw Blame History

🔍 Guide Recherche, PDF, Excel & Excalidraw

ObsiGate va au-delà de la simple lecture : recherche puissante, rendu des documents riches (PDF, diagrammes) et indexation de leur contenu pour que tout soit retrouvable.

Public : tous les utilisateurs Fiches techniques : features/semantic-search.md · features/pdf.md · features/excalidraw.md

1. Recherche plein texte (TF-IDF)

Le moteur d'ObsiGate s'appuie sur un index inversé et un scoring TF-IDF avec :

  • Boost titre — une correspondance dans le titre pèse 3× plus.
  • Normalisation des accents — resume trouve résumé, elephant trouve éléphant.
  • Stemming français — les variantes des mots sont rapprochées.
  • Snippets surlignés — les termes trouvés sont mis en <mark> dans l'extrait.
  • Facettes — compteurs par vault et par tag sur les résultats.
  • Pagination — 50 résultats par page.
  • Tri — par pertinence (TF-IDF) ou par date de modification.
  • Chips de filtres — les filtres actifs apparaissent sous forme de puces retirables.
  • Historique — les 50 dernières recherches sont conservées en localStorage.

La recherche s'effectue sans I/O disque : le contenu est déjà en mémoire.

2. Syntaxe de requête

Opérateur Description Exemple
tag:<nom> Filtre par tag tag:recette docker
#<nom> Raccourci de tag #linux serveur
vault:<nom> Filtre par vault vault:IT kubernetes
title:<texte> Filtre par titre title:pizza
path:<texte> Filtre par chemin path:recettes/soupes
ext:<type> Filtre par type de fichier ext:md kubernetes
"phrase exacte" Recherche d'une phrase tag:"multi mots"

Les opérateurs sont combinables :

tag:linux vault:IT ext:md serveur web

Cette requête cherche « serveur web » dans les fichiers Markdown de la vault IT portant le tag linux.

Filtres par extension

Extension Contenu
ext:md Notes Markdown
ext:py, ext:sh, ext:js Scripts et code
ext:pdf Documents PDF (texte extrait)
ext:excalidraw Diagrammes Excalidraw (texte extrait)

3. Autocomplétion et suggestions

  • /api/suggest — suggère des titres de fichiers.
  • /api/tags/suggest — suggère des tags.
  • Navigation clavier : ↑ / ↓ puis Entrée ; Échap ferme les suggestions.

Raccourcis de recherche

Raccourci Action
Ctrl + K / Cmd + K Focaliser la barre de recherche
/ Focaliser la recherche (hors champ texte)
↑ / ↓ Naviguer dans les suggestions
Entrée Sélectionner la suggestion active ou lancer la recherche
Échap Fermer les suggestions / quitter la recherche

Recherches sauvegardées et signets sont disponibles via l'API (/api/saved-searches, /api/bookmarks).

4. Recherche sémantique (optionnelle)

Au classement TF-IDF peut s'ajouter un classement par embeddings, fusionné via la méthode RRF (Reciprocal Rank Fusion). Activation : touche ~ (ou Alt + S) dans la recherche.

Deux modes :

  1. Sans dépendance — un embedder par hachage fournit une base utilisable immédiatement.
  2. Embeddings réels — installez backend/requirements-semantic.txt et/ou renseignez les variables OBSIGATE_EMBEDDING_* pour utiliser all-MiniLM-L6-v2.

Détails et configuration : features/semantic-search.md.

5. Support PDF

Lecture

Les fichiers PDF de vos vaults s'affichent en ligne dans le navigateur via le visualiseur PDF natif (iframe + <embed>). Le fichier est streamé en HTTP Range (206 Partial Content) : les gros PDF se chargent progressivement.

Recherche

Le texte est extrait à l'indexation (pypdf / pymupdf), donc le contenu des PDF est recherchable via la recherche plein texte. Utilisez ext:pdf pour limiter les résultats aux PDF.

Métadonnées

GET /api/file/{vault}/pdf/info renvoie les métadonnées (pages, titre, auteur) sans transférer le document.

curl "http://localhost:2020/api/file/Recettes/pdf/info?path=menu.pdf"

Limites

  • Pas d'OCR : les PDF scannés (images) ne sont pas recherchables.
  • Pas d'annotation ni d'édition du PDF lui-même.

6. Tableurs Excel (XLSX)

Affichage et édition

Un fichier .xlsx s'ouvre dans une visionneuse dédiée : un tableau par feuille, des onglets pour naviguer entre elles, les en-têtes A1/B1 et les numéros de ligne. Chaque cellule est modifiable directement (clic), Entrée valide, Échap annule la saisie. Enregistrer envoie les cellules modifiées à PUT /api/file/{vault}/xlsx/save : une sauvegarde par feuille, avec backup automatique du fichier avant écriture, et une écriture atomique (le classeur n'est jamais laissé à moitié écrit).

Avertissement avant enregistrement

Certains classeurs contiennent des éléments qu'ObsiGate ne sait pas réécrire : valeurs calculées mises en cache par Excel, segments (slicers), chronologies, contrôles de formulaire, connexions/requêtes, XML personnalisé, signature numérique, commentaires enrichis, macros. L'ouverture affiche alors un bandeau qui les liste, et la première sauvegarde demande confirmation. Si vous refusez, rien n'est écrit.

Les graphiques, images et tableaux croisés sont, eux, bien conservés.

Formules

Par sécurité, une valeur saisie commençant par = ou @ est stockée comme texte (une formule injectée s'exécuterait à l'ouverture du fichier dans Excel). Le bouton f(x) de la barre d'outils active les vraies formules pour la session en cours.

curl -X PUT "http://localhost:2020/api/file/Recettes/xlsx/save?path=budget.xlsx"   -H "Content-Type: application/json"   -d '{"sheet": "Budget", "cells": {"B1": "250"}, "allow_formula": false, "force": false}'
  • allow_formula : true pour écrire une vraie formule (=B1*2).
  • force : true pour enregistrer malgré les éléments non préservés (sinon l'API répond 409 xlsx_lossy_content).
  • Deux sauvegardes simultanées sur le même fichier : la seconde reçoit 409 conflict au lieu d'écraser la première.

Feuilles volumineuses et lecture par fenêtres

Le rendu est plafonné à 500 lignes × 40 colonnes par feuille. Quand une feuille dépasse ce plafond, un bandeau « Feuille tronquée » l'annonce explicitement (par exemple « 500 lignes affichées sur 520 ») au lieu de présenter une table courte comme complète — le classeur, lui, n'est jamais modifié. La ligne d'en-têtes de colonnes reste visible pendant le défilement vertical.

Côté API, GET /api/file/{vault}/xlsx/sheet sert une feuille par fenêtres de lignes, y compris au-delà du plafond d'affichage — les coordonnées A1 renvoyées sont celles de la feuille réelle :

curl "http://localhost:2020/api/file/Recettes/xlsx/sheet?path=budget.xlsx&sheet=Budget&offset=500&limit=200"
  • offset : première ligne renvoyée (0-based) ; limit : nombre de lignes (1 à 1 000 par requête).
  • La réponse porte total_rows, truncated et has_more pour paginer.
  • Erreurs : 404 si la feuille n'existe pas, 415 si le fichier n'est pas un .xlsx.

Limites

  • L'affichage intégré démarre à 500 lignes × 40 colonnes par feuille ; sous une feuille plus grande, le bouton « Charger la suite » (ou le défilement vers le bas du tableau) ajoute les lignes suivantes par fenêtres de 500 — elles deviennent aussitôt éditables et sauvegardables.
  • Styles, formats de nombre, cellules fusionnées et volets figés ne sont pas rendus.
  • Formats non gérés : .xls, .xlsm (macros), .ods.

7. Diagrammes Excalidraw

Les fichiers .excalidraw et .excalidraw.md (dont le format compressé du plugin Obsidian Excalidraw) s'ouvrent dans un éditeur visuel Excalidraw complet, dans une iframe sandboxée.

  • Dessin et édition sans quitter ObsiGate.
  • Sauvegarde automatique (débounce 2 s) ou Ctrl + S.
  • Thème clair/sombre suivi automatiquement.
  • Texte indexé : le texte des éléments du diagramme est extrait à l'indexation et donc recherchable (ext:excalidraw).

Fiche technique : features/excalidraw.md.

8. Autres contenus riches

Mermaid

Les blocs de code ```mermaid sont rendus en diagrammes interactifs (live preview, thèmes, zoom, plein écran, pré-processeur compatible syntaxe Obsidian).

Images Obsidian

Toutes les syntaxes d'images sont supportées avec résolution intelligente en 7 stratégies :

  1. chemin absolu ;
  2. dossier d'attachements configuré (VAULT_N_ATTACHMENTS_PATH) ;
  3. index de démarrage (correspondance unique) ;
  4. même répertoire que la note ;
  5. racine de la vault ;
  6. index de démarrage (correspondance la plus proche) ;
  7. repli : [image not found: fichier.ext].

Rescan manuel des attachements :

curl -X POST "http://localhost:2020/api/attachments/rescan/Recettes"

Graphe et backlinks

  • Graphe : vue force-directed (Barnes-Hut), filtres (tag, type), profondeur, mode focus, export PNG, aperçu au survol (Ctrl + clic).
  • Backlinks : GET /api/file/{vault}/backlinks?path=… liste les notes pointant vers un document.

9. Dépannage

Symptôme Piste
Un PDF ne s'affiche pas Vérifier la taille (OBSIGATE_PDF_MAX_SIZE_MB, défaut 50 Mo)
Le texte d'un PDF scanné n'est pas trouvé Pas d'OCR : normal
Une image reste introuvable Configurer VAULT_N_ATTACHMENTS_PATH, puis rescan
La recherche sémantique ne s'active pas Vérifier le toggle ~ et OBSIGATE_EMBEDDING_*
Résultats obsolètes Forcer une réindexation : GET /api/index/reload
Reference in New Issue View Git Blame Copy Permalink