137 lines
4.0 KiB
Markdown
137 lines
4.0 KiB
Markdown
# 📱 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.
|