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 :
- **Cache statique** : Interface et assets
- **Cache dynamique** : Données API (max 50 entrées)
- **Stratégies** : Cache-first et Network-first
- **Nettoyage** : Suppression automatique des anciens caches

### 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

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

```javascript
// 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

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

### Désinstaller le Service Worker

```javascript
// 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** :
```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 "public, max-age=3600";
    proxy_pass http://obsigate:8080;
}
```

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

## 🔒 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](https://developer.mozilla.org/en-US/docs/Web/Progressive_web_apps)
- [web.dev - PWA](https://web.dev/progressive-web-apps/)
- [PWA Builder](https://www.pwabuilder.com/)
- [Workbox (Google)](https://developers.google.com/web/tools/workbox)

## ❓ 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. 📖✨