ObsiGate/docs/PWA_GUIDE.md

Guide PWA - ObsiGate

ObsiGate est maintenant une Progressive Web App (PWA) complète, offrant une expérience d'application native sur tous les appareils.

🎯 Qu'est-ce qu'une PWA ?

Une Progressive Web App combine le meilleur du web et des applications natives :

• Installation : Installez ObsiGate sur votre appareil comme une application native
• Mode hors ligne : Accédez à vos notes même sans connexion internet
• Notifications : Recevez des alertes de mise à jour
• Performance : Chargement rapide grâce au cache intelligent
• Multi-plateforme : Fonctionne sur desktop, mobile et tablette

📱 Installation

Sur Desktop (Chrome, Edge, Brave)

1. Ouvrez ObsiGate dans votre navigateur
2. Cliquez sur l'icône d'installation dans la barre d'adresse (➕ ou ⬇️)
3. Cliquez sur "Installer" dans la popup
4. ObsiGate apparaît maintenant dans vos applications

Alternative : Menu ⋮ → "Installer ObsiGate..."

Sur Android

1. Ouvrez ObsiGate dans Chrome
2. Appuyez sur le menu ⋮ (trois points)
3. Sélectionnez "Ajouter à l'écran d'accueil"
4. Confirmez l'installation
5. L'icône ObsiGate apparaît sur votre écran d'accueil

Sur iOS/iPadOS (Safari)

1. Ouvrez ObsiGate dans Safari
2. Appuyez sur le bouton Partager 📤
3. Faites défiler et sélectionnez "Sur l'écran d'accueil"
4. Nommez l'application et appuyez sur "Ajouter"
5. ObsiGate apparaît sur votre écran d'accueil

⚡ Fonctionnalités PWA

Mode Hors Ligne

Le service worker met en cache :

• Interface utilisateur : HTML, CSS, JavaScript
• Ressources statiques : Icônes, polices
• Contenu API : Dernières données consultées

Stratégies de cache :

• Cache First : Assets statiques (interface)
• Network First : API et données dynamiques
• Fallback : Affichage gracieux en cas d'erreur

Mises à Jour Automatiques

• Vérification des mises à jour toutes les minutes
• Notification élégante quand une nouvelle version est disponible
• Mise à jour en un clic sans perte de données

Raccourcis d'Application

Accès rapide aux fonctionnalités depuis l'icône :

• Recherche : Ouvre directement la recherche

🛠️ Configuration Technique

Fichiers PWA

ObsiGate/
├── frontend/
│   ├── manifest.json          # Manifeste PWA
│   ├── sw.js                  # Service Worker
│   ├── icons/                 # Icônes PWA
│   │   ├── icon-72x72.svg
│   │   ├── icon-192x192.svg
│   │   ├── icon-512x512.svg
│   │   └── ...
│   ├── index.html             # Meta tags PWA
│   ├── app.js                 # Enregistrement SW
│   └── style.css              # Styles PWA
└── generate_pwa_icons.py      # Générateur d'icônes

Manifeste (manifest.json)

Définit les métadonnées de l'application :

• Nom et description
• Icônes (multiples tailles)
• Couleurs de thème
• Mode d'affichage (standalone)
• Raccourcis d'application

Service Worker (sw.js)

Gère le cache et le mode hors ligne (version SW_VERSION) :

• Code (HTML/JS/CSS/manifest) : network-first (cache en secours hors-ligne)
• API : network-first (+ cache hors-ligne)
• Autres assets (images, polices) : stale-while-revalidate
• Nettoyage : purge automatique des caches d'une version antérieure à l'activation

Le choix network-first est délibéré : les assets ne sont pas fingerprintés, un cache-first servait donc un ancien build indéfiniment sur mobile (BUG-005).

Icônes PWA

Tailles supportées :

• 72x72 : Favicon, petites icônes
• 96x96 : Raccourcis
• 128x128, 144x144, 152x152 : Appareils mobiles
• 192x192 : Android home screen (standard)
• 384x384 : Haute résolution
• 512x512 : Splash screens, maskable icons

Maskable icons : Icônes adaptatives avec safe zone pour Android

🔧 Génération des Icônes

Utilisation du Script

# Générer les icônes SVG
python generate_pwa_icons.py

Le script crée :

• Icônes régulières (toutes tailles)
• Icônes maskables (192x192, 512x512)
• Icône de recherche (96x96)
• README avec instructions de conversion

Conversion SVG → PNG (Production)

Option 1 : ImageMagick

cd frontend/icons
for file in *.svg; do
  size=$(echo $file | grep -oP '\d+x\d+' | head -1 | cut -d'x' -f1)
  convert -background none -resize ${size}x${size} "$file" "${file%.svg}.png"
done

Option 2 : Inkscape

cd frontend/icons
for file in *.svg; do
  size=$(echo $file | grep -oP '\d+x\d+' | head -1 | cut -d'x' -f1)
  inkscape "$file" --export-filename="${file%.svg}.png" --export-width=$size
done

Option 3 : Outils en ligne

• https://cloudconvert.com/svg-to-png
• https://convertio.co/svg-png/

Note : Les navigateurs modernes supportent les SVG directement, la conversion PNG est optionnelle.

🎨 Personnalisation

Modifier les Couleurs

Éditez frontend/manifest.json :

{
  "theme_color": "#2563eb",        // Couleur de la barre d'état
  "background_color": "#1a1a1a"    // Couleur de fond au lancement
}

Modifier les Icônes

1. Éditez generate_pwa_icons.py
2. Modifiez les fonctions create_svg_icon() et create_maskable_svg_icon()
3. Régénérez : python generate_pwa_icons.py

Ajouter des Raccourcis

Éditez frontend/manifest.json :

{
  "shortcuts": [
    {
      "name": "Nouvelle Note",
      "url": "/?action=new",
      "icons": [{"src": "/static/icons/new-96x96.png", "sizes": "96x96"}]
    }
  ]
}

🔍 Débogage

Vérifier l'Installation PWA

Chrome DevTools :

1. Ouvrez DevTools (F12)
2. Onglet "Application"
3. Section "Manifest" : Vérifiez les métadonnées
4. Section "Service Workers" : Vérifiez l'enregistrement
5. Section "Cache Storage" : Inspectez le cache

Tester le Mode Hors Ligne

1. DevTools → Onglet "Network"
2. Cochez "Offline"
3. Rechargez la page
4. L'application doit fonctionner avec les données en cache

Logs du Service Worker

// Dans la console du navigateur
navigator.serviceWorker.getRegistration().then(reg => {
  console.log('Service Worker:', reg);
  console.log('Active:', reg.active);
  console.log('Waiting:', reg.waiting);
});

Forcer la Mise à Jour

// Dans la console
navigator.serviceWorker.getRegistration().then(reg => {
  reg.update();
});

Désinstaller le Service Worker

// Dans la console
navigator.serviceWorker.getRegistrations().then(registrations => {
  registrations.forEach(reg => reg.unregister());
});

📊 Métriques PWA

Lighthouse Audit

1. Chrome DevTools → Onglet "Lighthouse"
2. Sélectionnez "Progressive Web App"
3. Cliquez sur "Generate report"

Critères évalués :

• ✅ Manifeste valide
• ✅ Service Worker enregistré
• ✅ HTTPS (ou localhost)
• ✅ Icônes appropriées
• ✅ Responsive design
• ✅ Mode hors ligne

Score Attendu

ObsiGate devrait obtenir 90-100/100 sur l'audit PWA.

🚀 Déploiement

Prérequis

• HTTPS obligatoire en production (sauf localhost)
• Service Worker nécessite une connexion sécurisée

Configuration Reverse Proxy

Nginx :

location /sw.js {
    add_header Cache-Control "no-cache, no-store, must-revalidate";
    add_header Service-Worker-Allowed "/";
    proxy_pass http://obsigate:8080;
}

location /manifest.json {
    add_header Cache-Control "no-cache";
    proxy_pass http://obsigate:8080;
}

# Les assets /static ne sont PAS fingerprintés : forcer la revalidation.
location /static/ {
    add_header Cache-Control "no-cache";
    proxy_pass http://obsigate:8080;
}

Traefik :

http:
  middlewares:
    sw-headers:
      headers:
        customResponseHeaders:
          Cache-Control: "no-cache, no-store, must-revalidate"
          Service-Worker-Allowed: "/"

Cloudflare (BUG-005)

Derrière Cloudflare, un service worker cache-first combiné à un en-tête Cache-Control: immutable sur des assets non fingerprintés peut servir un ancien build indéfiniment — même après « Purge Everything » : le Cache Storage du navigateur (Service Worker) est un stockage séparé que la purge Cloudflare et le « vider le cache » du téléphone ne touchent pas.

Correctifs appliqués côté code (ObsiGate ≥ 2.2.1) :

• SW network-first pour HTML/JS/CSS (cache seulement en secours hors-ligne), caches versionnés (SW_VERSION) purgés à l'activation.
• Cache-Control: no-cache sur /static, index.html, manifest.json et les pages HTML (revalidation ETag, pas de cache long).
• Migration ponctuelle localStorage qui supprime les anciens caches sur les appareils bloqués.

Réglages Cloudflare recommandés (dashboard → zone og.dracodev.net) :

Réglage	Valeur	Pourquoi
Rocket Loader	Désactivé	Réécrit/defer les scripts et casse les type="module".
Auto Minify (JS/CSS)	Désactivé	Peut casser la syntaxe JS moderne.
Cache Rules / Page Rules	Pas de « Cache Everything » sur HTML	Sinon Cloudflare ignore l'en-tête no-cache.
Browser Cache TTL	« Respect Existing Headers »	Laisse ObsiGate décider (no-cache).
WebSockets	Activé	Nécessaire aux connexions temps réel (SSE/WS).
Purge Cache	Après chaque déploiement	Évite un mix ancien/nouveau au premier accès.

Si un appareil reste bloqué malgré tout : sur mobile, désinstaller la PWA (ou « Site settings → Clear & reset ») puis rouvrir. La migration obsigate-sw-migration se charge normalement du nettoyage automatiquement.

🔒 Sécurité

Content Security Policy

Le service worker respecte la CSP définie dans le backend :

• Scripts : 'self' + CDN autorisés
• Styles : 'self' + CDN autorisés
• Images : 'self' + data URIs

Permissions

PWA installée demande les mêmes permissions que le site web :

• Aucune permission supplémentaire requise
• Notifications : optionnelles (désactivées par défaut)

📱 Compatibilité

Plateforme	Support	Notes
Chrome Desktop	✅ Complet	Installation native
Edge Desktop	✅ Complet	Installation native
Firefox Desktop	⚠️ Partiel	Pas d'installation, SW fonctionne
Safari Desktop	⚠️ Partiel	Support limité
Chrome Android	✅ Complet	Installation + notifications
Safari iOS	✅ Complet	"Add to Home Screen"
Samsung Internet	✅ Complet	Installation native

🎓 Ressources

• MDN - Progressive Web Apps
• web.dev - PWA
• PWA Builder
• Workbox (Google)

❓ FAQ

Q : Puis-je utiliser ObsiGate sans l'installer ?
R : Oui, l'installation est optionnelle. Le site web fonctionne normalement.

Q : Les données sont-elles synchronisées hors ligne ?
R : Non, le mode hors ligne utilise le cache local. Les modifications nécessitent une connexion.

Q : Comment désinstaller l'application ?
R : Desktop : Clic droit sur l'icône → "Désinstaller". Mobile : Maintenez l'icône → "Supprimer".

Q : Le cache prend-il beaucoup d'espace ?
R : Non, le cache est limité à ~50 entrées dynamiques + assets statiques (~5-10 MB).

Q : Puis-je désactiver le service worker ?
R : Oui, supprimez l'enregistrement dans DevTools ou commentez registerServiceWorker() dans app.js.

---

ObsiGate PWA - Vos notes Obsidian, partout, tout le temps. 📖✨