Files

T

bruno 31d4616baf feat: garde-fous d'écriture des classeurs Excel #153 (P0)

L'édition d'un .xlsx pouvait détruire une partie du classeur, le
concurrencer en silence, ou diffuser une injection de formule.

- BUG-085 : inspect_workbook() détecte ce qu'un round-trip openpyxl perd
  (valeurs calculées en cache, slicers, contrôles, connexions, custom
  XML, signature, commentaires enrichis, macros) → xlsx_lossy_features
  exposé en lecture, bandeau FR/EN, et 409 xlsx_lossy_content sans
  `force` (confirmation explicite puis reprise). Périmètre réel
  revalidé : graphiques, images et TCD survivent au round-trip.
- BUG-086 : écriture atomique (fichier .tmp + os.replace) : un plantage
  ne peut plus tronquer le classeur, le backup reste intact.
- BUG-087 : verrou par fichier autour du read-modify-write (timeout 15 s,
  409 conflict) ; endpoint xlsx/save devenu synchrone pour que
  l'attente s'exécute dans le threadpool.
- BUG-088 : une saisie en '=' ou '@' est stockée en texte, sauf opt-in
  `allow_formula` ou le bouton f(x) de la visionneuse. Le handler
  ServiceError expose désormais code + details, que api() propage.
- BUG-084 : la suppression d'une vault purge enfin l'index inversé
  (documents fantômes qui continuaient de matcher) et is_stale() devient
  is_ready(), le nom étant trompeur (la staleness n'existe plus).

Tests : 1390 pytest, 10 JSDOM (xlsx-viewer.test.mjs, branché au CI),
3 E2E Playwright, suite E2E complète verte, ruff/mypy 0.

🤖 Generated with Codebuff
Co-Authored-By: Codebuff <[email protected]>

2026-09-27 20:39:12 -04:00

8.6 KiB

Raw Blame History

🚀 Guide de prise en main

Ce guide vous fait passer d'une installation fraîche à une utilisation courante d'ObsiGate : première connexion, découverte de l'interface, navigation dans vos vaults Obsidian et raccourcis essentiels.

Public : tous les utilisateurs · Durée de lecture : ~10 min Voir aussi : Déploiement Docker · Recherche, PDF, Excel & Excalidraw · API REST

1. Qu'est-ce qu'ObsiGate ?

ObsiGate est une porte d'entrée web ultra-légère vers vos vaults Obsidian. Il indexe vos notes en mémoire, les rend accessibles depuis n'importe quel navigateur (ordinateur, tablette, téléphone) et ajoute une couche moderne : recherche avancée, lecture Markdown, liens [[wikilinks]], images, PDF, Excalidraw, Mermaid, assistant IA, collaboration temps réel.

Points clés :

Aucune modification de vos vaults : les volumes sont montés en lecture seule (:ro) par défaut.
Pas de base de données : tout l'état tient dans des fichiers JSON sous data/.
Temps réel : un watcher surveille le système de fichiers et met l'index à jour à chaud.
Multi-vault : plusieurs vaults peuvent être affichés et recherchés simultanément.

2. Prérequis

Composant	Version	Remarque
Docker	≥ 20.10	ou Node/`uv` pour un lancement manuel
docker-compose	≥ 2.0	inclus avec Docker Desktop
Navigateur	récent	Chrome, Edge, Firefox, Safari

Vous aurez aussi besoin du chemin absolu de chaque vault Obsidian sur la machine qui héberge Docker.

3. Lancer ObsiGate en 3 étapes

La procédure complète (reverse proxy, HTTPS, mises à jour) est détaillée dans le Guide de déploiement Docker.

3.1 Cloner le dépôt

git clone https://git.dracodev.net/Projets/ObsiGate.git
cd ObsiGate

3.2 Déclarer vos vaults

Éditez docker-compose.yml pour monter vos dossiers (chemins absolus, lecture seule) :

volumes:
  - /home/user/Documents/Obsidian-Recettes:/vaults/Recettes:ro
  - /home/user/Documents/Obsidian-IT:/vaults/IT:ro
  - ./data:/app/data   # persistance auth/config
environment:
  - VAULT_1_NAME=Recettes
  - VAULT_1_PATH=/vaults/Recettes
  - VAULT_2_NAME=IT
  - VAULT_2_PATH=/vaults/IT

Créez le fichier de secrets à partir du modèle :

cp .env.example .env
# Éditez .env (mot de passe admin, options d'auth…)

3.3 Construire et démarrer

chmod +x build.sh   # une seule fois
./build.sh

build.sh vérifie Docker, valide les volumes, construit l'image et démarre le conteneur. Ouvrez ensuite http://localhost:2020.

Options utiles : ./build.sh --help, ./build.sh --cache (rebuild rapide), ./build.sh --build-only (construire sans démarrer).

4. Premier accès

4.1 Si l'authentification est désactivée (défaut)

Vous arrivez directement sur l'interface. Toutes les fonctionnalités sont accessibles sans compte — à réserver à un usage sur réseau de confiance.

4.2 Si l'authentification est activée

L'écran de connexion s'affiche. Au tout premier démarrage, ObsiGate crée un compte admin et affiche le mot de passe une seule fois dans les logs :

docker compose logs obsigate | grep -A4 "FIRST"

Changez ce mot de passe dès la première connexion (menu → profil → Changer le mot de passe). La gestion complète des comptes, du MFA et des permissions est décrite dans le Guide Authentification & sécurité.

5. Découvrir l'interface

L'interface se compose de trois zones principales.

5.1 L'en-tête (header)

Élément	Rôle
🔍 Barre de recherche globale	Recherche dans toutes les vaults autorisées
Filtre	Restreint la recherche (type, tag, vault…)
Sélecteur de vault	Bascule l'arborescence sur une vault ou « Toutes les vaults »
Utilisateur	Nom du compte connecté (si auth activée)
Version	Version courante d'ObsiGate
⚙️ Options	Configuration, thème, guide d'utilisation, administration

5.2 La barre latérale (sidebar)

Elle regroupe les vues principales via des icônes :

Arborescence — parcourt les dossiers et fichiers de la vault sélectionnée.
Graphe — vue force-directed des liens entre notes.
Récents — derniers fichiers ouverts.
Signets — vos fichiers et recherches enregistrés.
Partagés — liens de partage public que vous avez créés.

Un champ « Filtrer fichiers… » restreint l'arborescence en temps réel, et le bouton Aa ajuste l'affichage des libellés.

En bas de la sidebar (si l'authentification est activée), la section compte affiche votre avatar (ou vos initiales), votre nom et votre rôle ; un clic ouvre le profil. La photo se choisit dans Configurations → Profil (Choisir une image : PNG, JPG ou WEBP — recadrée en carré 256 px, affichée dans le cercle de la sidebar) ; le bouton Se déconnecter est juste à côté.

5.3 La zone de contenu

Elle affiche l'onglet actif : tableau de bord Statistiques, Bookmarks, Récents, Partagés, ou le document ouvert. Les documents s'ouvrent dans des onglets (avec possibilité de vue multi-panneaux / split view).

Déployez une vault dans la sidebar (clic sur son nom).
Cliquez sur un dossier pour l'ouvrir, sur un fichier pour l'afficher.
Le breadcrumb en haut du document permet de remonter rapidement.
Les wikilinks [[note]] sont cliquables ; les images et diagrammes s'affichent automatiquement.
Utilisez Ctrl + clic sur un lien pour l'ouvrir en aperçu rapide selon le contexte, ou ouvrir le graphe centré sur un nœud.

Créer et modifier

Bouton « Editer » : ouvre le document dans l'éditeur Markdown (CodeMirror).
Bouton « Forge » (éditeur avancé) : ouvre la version enrichie avec assistant IA intégré. Voir Assistant IA & Forge.
Nouveau fichier / dossier : depuis les actions de la sidebar ou la palette de commandes.
Sauvegarde : Ctrl + S (et auto-sauvegarde dans l'éditeur IA).

Selon le mode, la lecture et l'édition se remplacent : Editer et Forge prennent la place de la vue lecture ; revenez avec ✓ / × ou Échap.

7. Rechercher

La recherche est un point fort d'ObsiGate : index inversé TF-IDF, stemming français, normalisation des accents, facettes et pagination. La syntaxe complète (tag:, #, vault:, title:, path:, ext:, phrases exactes) est décrite dans le Guide Recherche, PDF, Excel & Excalidraw.

Démarrage rapide :

Tapez dans la barre de recherche, Ctrl + K pour y revenir.
/ focalise la recherche hors champ de saisie.
/ + ↑/↓ navigue dans les suggestions.

8. Apparence et confort

Thème clair/sombre : bascule persistée en localStorage ; le desktop suit aussi le thème du système.
Thèmes : clair, sombre, contraste élevé, sépia — import/export possible.
Responsive : l'interface s'adapte au mobile (éditeur tactile, barre d'outils flottante).
PWA : installable comme application native, mode hors-ligne partiel.

Voir PWA & mode hors-ligne.

9. Raccourcis clavier essentiels

Action	Raccourci
Palette de commandes	`Ctrl + Shift + Space`
Palette de fichiers (navigation rapide)	`Ctrl + Alt + Space`
Focus barre de recherche	`Ctrl + K`
Recherche rapide (hors champ texte)	`/`
Sauvegarder le fichier ouvert	`Ctrl + S`
Rechercher dans le document	`Ctrl + F`
Completion IA inline (éditeur)	`Ctrl + J`
Insertion rapide (éditeur Forge)	`Alt + I`
Fermer l'éditeur / modale	`Échap`
Aide de l'éditeur Forge	`F1`
Naviguer dans les suggestions	`↑` / `↓`
Lancer la recherche / valider	`Entrée`

Le panneau Raccourcis & Astuces du tableau de bord Statistiques récapitule ces raccourcis directement dans l'application.

10. Et ensuite ?

Objectif	Guide
Mieux chercher, lire PDF/Excel et Excalidraw	Recherche, PDF, Excel & Excalidraw
Utiliser l'IA intégrée	Assistant IA & Forge
Éditer à plusieurs	Édition & collaboration
Sécuriser l'accès	Authentification & sécurité
Automatiser via API/MCP	API REST · MCP
Installer l'application native	Desktop (Tauri)

8.6 KiB Raw Blame History Unescape Escape