Après ~35 features livrées (#70→#104), le guide intégré (modale « Guide d'utilisation », #help-modal de frontend/index.html) ne représentait plus l'application : Mermaid, hors-ligne/PWA, collaboration Yjs, desktop Tauri, exports HTML/ePub/ZIP, recherche sémantique, MFA/WebAuthn, push, split view, API OpenAPI/MCP étaient absents. L'item couvre quatre livrables :

Audit de couverture — toutes les fonctionnalités visibles ET non visibles (API, MCP, webhooks, endpoints de partage) sont documentées.
Section Architecture — diagramme Mermaid des grandes composantes.
Téléchargement Markdown + PDF du guide, dans la langue courante.
Lecture desktop élargie (mode Tauri + grands viewports web).

2. Source de vérité du contenu

Le contenu des nouvelles sections vit dans scripts/guide_content.py : dictionnaire CONTENT (clé → FR, EN) + constructeurs HTML qui ne peuvent pas diverger des locales (le FR inline est généré depuis CONTENT).

scripts/merge_guide_locales.py → injecte les clés guide105.* dans frontend/locales/{fr,en}.json (insertion textuelle, parité assertée).
scripts/insert_guide_sections.py → insère sections/TOC/compléments dans index.html (idempotent, préserve les fins de ligne, vérifie l'équilibre <section> et l'absence d'ancre morte).
Règle : ne jamais éditer les blocs guide105.* des JSON ni les sections #105 de index.html à la main — modifier guide_content.py et relancer les deux scripts (séquence figée, sinon HTML et locales divergent).

3. Rendu du guide dans l'app

Les textes portent data-i18n="guide105.*" ; _applyDOM() (i18n.js) les remplit avec la locale courante. Les valeurs FR/EN contiennent du HTML minimal (<code>, <strong>, <a href="https://…">) — sûre ici car ces chaînes sont statiques dans le dépôt (jamais de contenu utilisateur ; même convention que help.desc_* existant).

Le diagramme d'architecture est un bloc <pre class="mermaid-code"><code class="language-mermaid"> : à l'ouverture de la modale, renderGuideMermaid() (config.js) appelle renderMermaidBlocks() (mermaid-viewer.js) sur la modale — le viewer ne rend que les vues document, la modale est donc enrichie ici. Si le CDN Mermaid n'est pas prêt, le bloc reste du code lisible et le rendu est retenté à l'ouverture suivante (data-mermaid-rendered ne se pose qu'après succès). Le MD exporté embarque le diagramme en fenced block ```mermaid (copiable, rendu par GitHub/VS Code/Obsidian) ; le PDF contient le même bloc.

4. Téléchargement (MD + PDF)

backend/guide_export.py : parseur stdlib (html.parser → arbre minimal) ; extraction de #help-modal→.help-content, résolution i18n identique à _applyDOM (un élément data-i18n est remplacé par la valeur locale, sinon le FR inline sert de repli), conversion Markdown (titres, listes imbriquées, tables, fenced code, gras/italique/code/kbd/links http) et HTML propre pour WeasyPrint. PDF : pipeline d'export existant (build_pdf_html + generate_pdf), repli _render_reportlab_pdf (markdown simplifié) quand GTK manque (Windows nu) — même stratégie que le bouton « PDF » des documents (#92). get_guide_document(fmt, lang) met en cache (octets+signature mtime/size de index.html et fr.json) pour éviter de re-générer à chaque requête.

Endpoint GET /api/guide/download?format=md|pdf&lang=fr|en (require_auth, tag OpenAPI « Guide »), Content-Disposition: attachment. Côté UI : boutons « Markdown » / « PDF » dans l'en-tête de la modale (#help-download-md/#help-download-pdf), handler downloadGuide() dans frontend/js/config.js — fetch avec AuthManager.getAuthHeaders() + credentials (identique à viewer.downloadExport()), blob → lien téléchargeable, toasts i18n réutilisés (viewer.export_*).

5. Guide desktop élargi

frontend/js/desktop.js::initDesktopIntegration() ajoute body.desktop-mode (une fois, après le garde Tauri). CSS (section « Help Modal: desktop » de style.css) : conteneur 1760 px / 96 vw, contenu 1440 px, modale 94 vh ; le même layout est accordé aux viewports ≥1400 px web via media-query (contenu 1280 px). Le mobile reste inchangé (≤768 px plein écran).

6. Couverture fonctionnelle du guide (après #105)

Domaine app	Section du guide
Vaults, arborescence, filtres, breadcrumb	Interface, Navigation
Onglets, popout, split view	Onglets, Personnalisation
Recherche TF-IDF, opérateurs, facettes, sémantique, recherches sauvegardées, signets	Recherche, Bibliothèque
Tags, frontmatter	Tags
Fichiers, types supportés, CodeMirror, PDF, export HTML/ePub/ZIP, anti-doublons upload	Fichiers
Mermaid	Diagrammes
Excalidraw	Excalidraw
Éditeur, AI toolbar, BooksLM, commandes @//, skills, images, outils, historique	Édition, IA
Édition mobile	Mobile (section dédiée, BUG-067)
Graphe, backlinks	Bibliothèque, Graphe
Palette de commandes, raccourcis	Palette, Raccourcis
Partage public, PDF du partage, webhooks HMAC	Partage, Webhooks
Backups, diff, purge, audit log, gestionnaire	Sauvegardes et Audits
JWT/Argon2id, rate limit, MFA TOTP/WebAuthn, admin dashboard, secrets, CSP	Sécurité
PWA hors-ligne, IndexedDB queue, watcher, conflits Syncthing	Hors-ligne, Bibliothèque
Collaboration Yjs/CRDT, awareness, push VAPID	Collaboration, Interface
Tauri desktop (updater signé, wizard, fenêtrage)	Desktop
API REST OpenAPI (/docs, /redoc, /api, /openapi.json), MCP /mcp, automatisation	API & Intégrations
i18n FR/EN, export du guide multilingue	Multilingue
Architecture technique (couches, flux, données, déploiement)	Architecture (nouveau)
Plugins sandboxés	Plugins

7. Tests & vérifications

tests/test_guide.py (11) : ancre TOC→sections (garde-fou BUG-067), sections #105 présentes, parité/présence des clés guide105.* FR=EN, Markdown FR/EN (titres, mermaid, absence de balises résiduelles), PDF (%PDF, taille), metadata get_guide_document, endpoint MD/PDF/400 via TestClient, OpenAPI (path + tag « Guide »).
Suite backend pytest : 1216 passed · ruff/mypy 0 erreur · validate-imports 38 modules · unit.test.mjs 10/10 · E2E complet CI.
SW cache busting : SW_VERSION v21→v22.

8. Limites assumées

Le PDF est généré côté serveur avec les polices système ; en l'absence de GTK (Windows de dev) c'est le repli reportlab (sans tableaux) — la voie WeasyPrint est celle des conteneurs Docker/prod.
Le sommaire et les sections sont en dur dans index.html : tout ajout futur de section passe par guide_content.py + les deux scripts (jamais à la main).

7.0 KiB Raw Blame History

#105 — Guide d'utilisation : couverture, téléchargement MD/PDF, Architecture

1. Objectif