# 🔍 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/semantic-search.md) ·
> [`features/pdf.md`](../features/pdf.md) · [`features/excalidraw.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** :

```text
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`](../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.

```bash
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.

```bash
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 :

```bash
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`](../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 :

```bash
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` |