fix(pwa): BUG-005 chargement mobile via Cloudflare (SW network-first + no-cache)

docs/PWA_GUIDE.md

@@ -94,11 +94,14 @@ Définit les métadonnées de l'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
+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
 
@@ -271,7 +274,13 @@ location /sw.js {
 }
 
 location /manifest.json {
-    add_header Cache-Control "public, max-age=3600";
+    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;
 }
 ```
@@ -287,6 +296,38 @@ http:
           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