# 📱 Guide PWA & mode hors-ligne

ObsiGate est une **Progressive Web App (PWA)** : installez-la comme une
application native, consultez vos notes **hors-ligne**, recevez des
notifications et synchronisez vos modifications à la reconnexion.

> **Public :** tous les utilisateurs · **Guides techniques :**
> [`PWA_GUIDE.md`](../PWA_GUIDE.md) · [`INSTALLATION_PWA.md`](../INSTALLATION_PWA.md)
> **Voir aussi :** [Prise en main](./PRISE_EN_MAIN.md) · [Édition & collaboration](./COLLABORATION.md)

---

## 1. Qu'est-ce que la PWA d'ObsiGate ?

Une PWA combine le meilleur du web et du natif :

- **Installation** sur l'écran d'accueil, sans store.
- **Mode hors-ligne** : interface et dernières données consultées mises en cache.
- **Notifications** : alertes de mise à jour et Web Push.
- **Performance** : chargement rapide via cache intelligent.
- **Multi-plateforme** : desktop, mobile, tablette.

---

## 2. Installer la PWA

### Desktop (Chrome, Edge, Brave)

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

*Alternative :* menu ⋮ → **Installer ObsiGate…**

### Android (Chrome)

1. Ouvrez ObsiGate dans Chrome.
2. Menu ⋮ → **Ajouter à l'écran d'accueil**.
3. Confirmez.

### iOS / iPadOS (Safari)

1. Ouvrez ObsiGate dans Safari.
2. Bouton Partager 📤 → **Sur l'écran d'accueil**.
3. Nommez l'application puis **Ajouter**.

---

## 3. Mode hors-ligne

Le **Service Worker** (`frontend/sw.js`) met en cache :

- l'interface (HTML, CSS, JavaScript, manifeste) ;
- les ressources statiques (icônes, polices) ;
- les dernières données API consultées.

### Stratégies de cache

| Ressource | Stratégie |
|---|---|
| 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 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 servirait indéfiniment un ancien build sur mobile.

### File de synchronisation & conflits

- Les modifications faites hors-ligne sont stockées (IndexedDB) et rejouées à la
  reconnexion.
- Les conflits éventuels sont détectés et peuvent être résolus (écran
  **Conflits**, `GET /api/conflicts`).

### Tester hors-ligne

1. DevTools (F12) → onglet **Network**.
2. Cochez **Offline**.
3. Rechargez : l'application doit fonctionner avec le cache.

---

## 4. Notifications (Web Push)

- Abonnement à partir de l'interface (permission navigateur requise).
- Endpoints : `GET /api/push/vapid-public-key`,
  `POST /api/push/subscribe`, `DELETE /api/push/subscribe`,
  `GET /api/push/subscriptions`.
- Les notifications sont signées **VAPID** et peuvent prévenir de changements
  (collaboration, mises à jour).

---

## 5. Mises à jour

- Vérification régulière des mises à jour.
- Notification quand une nouvelle version est disponible.
- Mise à jour en un clic, **sans perte de données**.
- Le numéro `SW_VERSION` invalide l'ancien cache à chaque livraison.

### Forcer une mise à jour (console)

```javascript
navigator.serviceWorker.getRegistration().then(reg => reg.update());
```

---

## 6. Débogage

### Vérifier l'installation

Chrome DevTools → onglet **Application** :

- **Manifest** : métadonnées ;
- **Service Workers** : enregistrement ;
- **Cache Storage** : contenu du cache.

### Désinstaller le Service Worker

```javascript
navigator.serviceWorker.getRegistrations().then(regs => regs.forEach(r => r.unregister()));
```

---

## 7. Limites

- Le hors-ligne dépend des données déjà mises en cache.
- Les actions d'écriture hors-ligne s'appliquent à la reconnexion (pas en temps
  réel).
- iOS applique des contraintes spécifiques (persistance, notifications).

Voir [Édition & collaboration](./COLLABORATION.md) pour le temps réel.