bruno
31d4616baf
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]>
243 lines
8.6 KiB
Markdown
243 lines
8.6 KiB
Markdown
# 🚀 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](./DEPLOIEMENT_DOCKER.md) ·
|
||
> [Recherche, PDF, Excel & Excalidraw](./RECHERCHE_PDF_EXCALIDRAW.md) ·
|
||
> [API REST](./API_REST.md)
|
||
|
||
---
|
||
|
||
## 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](./DEPLOIEMENT_DOCKER.md).
|
||
|
||
### 3.1 Cloner le dépôt
|
||
|
||
```bash
|
||
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) :
|
||
|
||
```yaml
|
||
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 :
|
||
|
||
```bash
|
||
cp .env.example .env
|
||
# Éditez .env (mot de passe admin, options d'auth…)
|
||
```
|
||
|
||
### 3.3 Construire et démarrer
|
||
|
||
```bash
|
||
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** :
|
||
|
||
```bash
|
||
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é](./AUTHENTIFICATION_SECURITE.md).
|
||
|
||
---
|
||
|
||
## 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).
|
||
|
||
---
|
||
|
||
## 6. Navigation et lecture
|
||
|
||
1. **Déployez une vault** dans la sidebar (clic sur son nom).
|
||
2. **Cliquez sur un dossier** pour l'ouvrir, sur un **fichier** pour l'afficher.
|
||
3. Le **breadcrumb** en haut du document permet de remonter rapidement.
|
||
4. Les **wikilinks** `[[note]]` sont cliquables ; les images et diagrammes
|
||
s'affichent automatiquement.
|
||
5. 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](./ASSISTANT_IA_FORGE.md).
|
||
- **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](./RECHERCHE_PDF_EXCALIDRAW.md).
|
||
|
||
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](./PWA_HORS_LIGNE.md).
|
||
|
||
---
|
||
|
||
## 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](./RECHERCHE_PDF_EXCALIDRAW.md) |
|
||
| Utiliser l'IA intégrée | [Assistant IA & Forge](./ASSISTANT_IA_FORGE.md) |
|
||
| Éditer à plusieurs | [Édition & collaboration](./COLLABORATION.md) |
|
||
| Sécuriser l'accès | [Authentification & sécurité](./AUTHENTIFICATION_SECURITE.md) |
|
||
| Automatiser via API/MCP | [API REST](./API_REST.md) · [MCP](./MCP.md) |
|
||
| Installer l'application native | [Desktop (Tauri)](./DESKTOP.md) |
|