@movalib/movalib-commons 1.68.32 → 1.68.34

package/.claude/PROMPT_fix-404-navigation.md

@@ -0,0 +1,237 @@
+# Diagnostic & Fix — 404 à la navigation après useNavigationRefresh
+
+## Symptôme
+
+Depuis l'implémentation de `useNavigationRefresh`, naviguer vers une route SPA (`/factures`, `/clients`, etc.) affiche la page 404. Rester sur la 404 et changer l'URL ne résout pas le problème — seul un reload complet depuis `/` le fait.
+
+---
+
+## Analyse du symptôme
+
+Ce comportement confirme **deux problèmes simultanés** :
+
+### Problème 1 — CloudFront ne redirige pas les 404 vers `index.html` (cause racine)
+
+Quand `useNavigationRefresh` fait `window.location.href = "/factures"`, il envoie une **vraie requête HTTP** vers S3. S3 n'a pas de fichier `/factures` → retourne une 404 → CloudFront sert `404.html`. L'app React est déchargée. On est maintenant sur une page HTML statique, plus dans la SPA. Changer l'URL dans la barre d'adresse envoie de nouvelles requêtes HTTP → toujours 404.
+
+**Sans une custom error response CloudFront (`404 → /index.html` avec status 200), tout hard refresh sur une route SPA est fatal.**
+
+### Problème 2 — `useNavigationRefresh` se déclenche trop tôt (cause secondaire)
+
+Si `__BUILD_TIME__` (injecté par Vite au build) ne matche pas exactement le `buildTime` dans `version.json` (écrit par `generate-version.js`), `useVersionCheck` détecte une "nouvelle version" dès le premier poll après le mount → `swUpdateFound` fire → `updatePending.current = true` → **toutes les navigations** deviennent des hard refreshes, même sans vrai changement de version.
+
+---
+
+## Travail demandé
+
+### Partie 1 — Fix infra CloudFront (à faire en PREMIER, manuellement)
+
+> ⚠️ Cette partie n'est pas du code. Elle doit être exécutée en ligne de commande **avant** tout fix client. Sans elle, le fix client ne sert à rien.
+
+**Étape 1 — Récupérer la config actuelle**
+```bash
+aws cloudfront get-distribution-config --id E2ILRWTFEVONPB > /tmp/dist-config.json
+cat /tmp/dist-config.json | python3 -c "import sys,json; d=json.load(sys.stdin); print('ETag:', d['ETag']); print('CustomErrorResponses:', json.dumps(d['DistributionConfig'].get('CustomErrorResponses', {}), indent=2))"
+```
+
+**Étape 2 — Vérifier si la custom error response existe déjà**
+
+Si la sortie contient un objet avec `"ErrorCode": 404` et `"ResponsePagePath": "/index.html"` → la config existe, passer à la partie 2.
+
+Si `CustomErrorResponses` est vide ou absent → ajouter la règle :
+
+```bash
+# Extraire l'ETag (affiché par la commande ci-dessus)
+ETAG="EXXXXXXXXXX"  # remplacer par la vraie valeur
+
+# Extraire et modifier la config
+python3 << 'EOF'
+import json
+
+with open('/tmp/dist-config.json') as f:
+    data = json.load(f)
+
+config = data['DistributionConfig']
+
+# Ajouter la custom error response SPA
+config['CustomErrorResponses'] = {
+    "Quantity": 2,
+    "Items": [
+        {
+            "ErrorCode": 404,
+            "ResponsePagePath": "/index.html",
+            "ResponseCode": "200",
+            "ErrorCachingMinTTL": 0
+        },
+        {
+            "ErrorCode": 403,
+            "ResponsePagePath": "/index.html",
+            "ResponseCode": "200",
+            "ErrorCachingMinTTL": 0
+        }
+    ]
+}
+
+with open('/tmp/dist-config-updated.json', 'w') as f:
+    json.dump(config, f, indent=2)
+
+print("✅ Config mise à jour dans /tmp/dist-config-updated.json")
+EOF
+
+# Appliquer
+aws cloudfront update-distribution \
+  --id E2ILRWTFEVONPB \
+  --if-match "$ETAG" \
+  --distribution-config file:///tmp/dist-config-updated.json
+```
+
+> Le 403 est ajouté en plus du 404 : S3 peut retourner 403 (au lieu de 404) sur certaines configs de bucket policy. Les deux doivent être couverts.
+> `ErrorCachingMinTTL: 0` est important : sans ça CloudFront peut mettre en cache les 404 et les re-servir pendant plusieurs minutes après le fix.
+
+---
+
+### Partie 2 — Diagnostic dans le code
+
+#### 2a. Vérifier l'alignement `__BUILD_TIME__` ↔ `version.json`
+
+Dans `generate-version.js`, récupérer la valeur exacte écrite dans `buildTime`.
+Dans `vite.config.ts`, récupérer la valeur exacte injectée dans `__BUILD_TIME__`.
+
+**Les deux doivent être issues de la même source, au même moment du build.** Le pattern correct :
+
+```js
+// generate-version.js — DOIT s'exécuter AVANT vite build
+// et écrire le même timestamp que celui lu par vite.config
+
+const buildTime = new Date().toISOString();
+// écrire buildTime dans public/version.json
+```
+
+```ts
+// vite.config.ts
+import { execSync } from 'child_process';
+
+// Lire le fichier version.json écrit par generate-version.js
+// NE PAS recalculer un nouveau Date.now() ici → ça crée un mismatch
+import versionJson from './public/version.json';
+
+export default defineConfig({
+  define: {
+    __BUILD_TIME__: JSON.stringify(versionJson.buildTime),
+  }
+})
+```
+
+Si `vite.config.ts` recalcule sa propre date au lieu de lire `version.json` → les deux valeurs seront toujours différentes → `swUpdateFound` fire systématiquement → **corriger cet alignement en priorité**.
+
+#### 2b. Ajouter un log temporaire de diagnostic dans `useVersionCheck.ts`
+
+Ajouter temporairement (à retirer après validation) :
+
+```ts
+if (buildTime !== __BUILD_TIME__ && buildTime !== dismissedVersion) {
+  // LOG TEMPORAIRE — retirer après diagnostic
+  console.warn('[useVersionCheck] Mismatch détecté', {
+    buildTime,
+    __BUILD_TIME__,
+    dismissedVersion,
+    match: buildTime === __BUILD_TIME__
+  });
+  updateDetected.current = true;
+  document.dispatchEvent(new CustomEvent("swUpdateFound", { detail: { buildTime } }));
+}
+```
+
+Ce log permettra de voir en console si `swUpdateFound` fire immédiatement au mount (mismatch permanent) ou seulement après un vrai déploiement.
+
+---
+
+### Partie 3 — Renforcer `useNavigationRefresh.ts`
+
+Le hook doit être rendu **défensif** contre les cas dégénérés :
+
+```ts
+import { useEffect, useRef } from "react";
+import { useHistory } from "react-router-dom";
+
+export function useNavigationRefresh() {
+  const history = useHistory();
+  const updatePending = useRef(false);
+  // Cooldown : si un refresh a déjà été tenté récemment, ne pas reboucler
+  const lastRefreshAttempt = useRef(0);
+  const REFRESH_COOLDOWN = 30_000; // 30s
+
+  useEffect(() => {
+    const onUpdate = () => {
+      console.log('[useNavigationRefresh] swUpdateFound reçu — refresh activé à la prochaine navigation');
+      updatePending.current = true;
+    };
+    const onDismiss = () => {
+      console.log('[useNavigationRefresh] swUpdateDismissed — refresh désactivé');
+      updatePending.current = false;
+    };
+
+    document.addEventListener("swUpdateFound", onUpdate);
+    document.addEventListener("swUpdateDismissed", onDismiss);
+
+    const unlisten = history.listen((location, action) => {
+      if (!updatePending.current) return;
+
+      // Anti-boucle : ne pas retenter un refresh dans les 30s
+      if (Date.now() - lastRefreshAttempt.current < REFRESH_COOLDOWN) {
+        console.warn('[useNavigationRefresh] Cooldown actif, refresh ignoré');
+        return;
+      }
+
+      // Pas de refresh sur bouton retour navigateur
+      if (action === "POP") return;
+
+      const destination = location.pathname + location.search + location.hash;
+      const current = window.location.pathname + window.location.search + window.location.hash;
+
+      // Pas de refresh si même URL (évite boucle sur lien actif)
+      if (destination === current) return;
+
+      console.log('[useNavigationRefresh] Hard refresh vers', destination);
+      lastRefreshAttempt.current = Date.now();
+      window.location.href = destination;
+    });
+
+    return () => {
+      document.removeEventListener("swUpdateFound", onUpdate);
+      document.removeEventListener("swUpdateDismissed", onDismiss);
+      unlisten();
+    };
+  }, [history]);
+}
+```
+
+---
+
+### Partie 4 — Nettoyage après validation
+
+Une fois que les logs de diagnostic confirment que tout fonctionne (le mismatch `__BUILD_TIME__` est corrigé, CloudFront redirige vers `index.html`, `useNavigationRefresh` ne fire que sur vrai changement de version) :
+
+1. Retirer les `console.log` / `console.warn` de diagnostic de `useVersionCheck.ts` et `useNavigationRefresh.ts`.
+2. Garder uniquement les `console.warn` d'anomalie (cooldown, etc.) en mode `process.env.NODE_ENV === 'development'`.
+
+---
+
+## Ordre d'exécution
+
+1. **Fix CloudFront** (Partie 1) — à faire manuellement en CLI, sans redéployer l'app.
+2. **Vérifier l'alignement `__BUILD_TIME__`** (Partie 2a) — corriger si nécessaire dans `vite.config.ts`.
+3. **Ajouter les logs temporaires** (Partie 2b) + **renforcer `useNavigationRefresh`** (Partie 3) — laisser Claude Code faire les modifications.
+4. **Redéployer** et vérifier en console que `swUpdateFound` ne fire pas immédiatement au mount.
+5. **Nettoyer** les logs une fois validé (Partie 4).
+
+---
+
+## Fichiers à modifier
+
+| Fichier | Action |
+|---|---|
+| `vite.config.ts` | Vérifier que `__BUILD_TIME__` lit `version.json` au lieu de recalculer `Date.now()` |
+| `src/hooks/useVersionCheck.ts` | Ajouter log temporaire de diagnostic du mismatch |
+| `src/hooks/useNavigationRefresh.ts` | Ajouter cooldown anti-boucle + logs de diagnostic |
+| CloudFront (CLI) | Ajouter custom error response 404+403 → `/index.html` (Partie 1, hors code) |

package/.claude/PROMPT_version-refresh-cleanup.md

@@ -0,0 +1,157 @@
+# Prompt Claude Code — Hard refresh à la navigation + nettoyage du système de version
+
+## Contexte
+
+`movalib-pro` est une SPA React/TypeScript sous Vite, déployée sur S3 + CloudFront.
+
+Le système de déploiement a été modifié pour **conserver les 3 dernières générations de chunks hashés** sur le bucket S3 (rétention générationnelle dans le script de deploy). En conséquence, les anciens chunks ne 404 plus immédiatement — mais un utilisateur peut rester sur une vieille version jusqu'à ce qu'il recharge la page.
+
+La stratégie retenue pour forcer la mise à jour : **hard refresh silencieux au changement d'URL**, uniquement si une nouvelle version a été détectée. Pas de reload brutal en plein travail, pas de perte de saisie : le refresh est déclenché à l'instant où l'utilisateur navigue vers une nouvelle route, il atterrit directement sur la destination en dernière version.
+
+## Ce qui existe déjà (ne pas recréer)
+
+### `src/hooks/useVersionCheck.ts`
+Poll `version.json` toutes les 5 minutes et au clic. Si `buildTime !== __BUILD_TIME__`, dispatche un `CustomEvent("swUpdateFound", { detail: { buildTime } })` sur `document`. Gestion du dismiss via `localStorage` (clé `swDismissedVersion`).
+
+```ts
+declare const __BUILD_TIME__: string;
+// → injecté par vite.config via define: { __BUILD_TIME__: ... }
+```
+
+### `src/utils/chunkErrorUtils.ts`
+Contient `isChunkLoadError(error)`, `canAutoReload()` et `markReloadTimestamp()` — gestion du cooldown pour éviter les boucles de reload lors d'un chunk 404.
+
+### `src/utils/lazyWithRetry.ts`
+Wrapper `React.lazy()` qui catch les erreurs de chunk et appelle `canAutoReload()` / `markReloadTimestamp()` avant de faire `window.location.reload()`.
+
+### `index.html`
+Contient un listener inline `vite:preloadError` qui fait un `window.location.reload()` **sans garde anti-boucle** (voir problème 1 ci-dessous).
+
+### Snackbar / notification UI
+Une snackbar MUI écoute `swUpdateFound` et affiche « Nouvelle version disponible » avec un bouton « Recharger ». Elle dispatche `swUpdateDismissed` si l'utilisateur ferme.
+
+### Router
+`react-router-dom` v5 avec `BrowserRouter`. L'objet `history` est accessible via `useHistory()` hook ou via un `history` singleton créé avec `createBrowserHistory()`.
+
+---
+
+## Travail demandé
+
+### 1. Aligner la garde anti-boucle du listener `vite:preloadError` dans `index.html`
+
+**Problème** : le listener inline fait un `reload()` inconditionnel. Si le reload tombe encore sur un index.html périmé, on boucle indéfiniment.
+
+**Fix** : ajouter une garde basée sur `sessionStorage`, avec la **même clé et le même cooldown** que `chunkErrorUtils.ts` pour que les deux mécanismes partagent le même état. Récupère la clé et la durée de cooldown depuis `chunkErrorUtils.ts` et aligne le listener en conséquence.
+
+```html
+<!-- index.html — remplacer le listener existant par : -->
+<script>
+  window.addEventListener("vite:preloadError", function (event) {
+    event.preventDefault();
+    // ⚠️ clé et cooldown IDENTIQUES à ceux de chunkErrorUtils.ts
+    var KEY = "chunk-reload-ts"; // à aligner sur canAutoReload()
+    var COOLDOWN = 10000;        // à aligner sur canAutoReload()
+    var last = Number(window.sessionStorage.getItem(KEY) || 0);
+    if (Date.now() - last > COOLDOWN) {
+      window.sessionStorage.setItem(KEY, String(Date.now()));
+      window.location.reload();
+    }
+  });
+</script>
+```
+
+Vérifie dans `chunkErrorUtils.ts` les valeurs exactes de la clé et du cooldown avant d'appliquer.
+
+---
+
+### 2. Ajouter le hard refresh à la navigation
+
+**Objectif** : quand `swUpdateFound` a été reçu (nouvelle version détectée), intercepter le prochain changement de route react-router et faire un `window.location.href = destination` au lieu de laisser le routeur faire une navigation client.
+
+**Règles impératives** :
+- Le refresh est **conditionnel** : uniquement si une nouvelle version a été détectée. Jamais systématique.
+- L'utilisateur atterrit sur **la page de destination**, pas sur la page courante (`window.location.href = to.pathname + to.search`, pas `window.location.reload()`).
+- Ne jamais déclencher le refresh sur la **même URL** (évite une boucle si l'utilisateur clique sur un lien actif).
+- Respecter le **dismiss** : si l'utilisateur a dismissé la notif (`swUpdateDismissed`), ne pas forcer le refresh non plus.
+
+**Implémentation suggérée** — créer un hook `src/hooks/useNavigationRefresh.ts` :
+
+```ts
+import { useEffect, useRef } from "react";
+import { useHistory } from "react-router-dom";
+
+export function useNavigationRefresh() {
+  const history = useHistory();
+  const updatePending = useRef(false);
+
+  useEffect(() => {
+    const onUpdate = () => { updatePending.current = true; };
+    const onDismiss = () => { updatePending.current = false; };
+
+    document.addEventListener("swUpdateFound", onUpdate);
+    document.addEventListener("swUpdateDismissed", onDismiss);
+
+    const unlisten = history.listen((location, action) => {
+      if (!updatePending.current) return;
+      if (action === "POP") return; // bouton retour navigateur → pas de reload
+      const destination = location.pathname + location.search + location.hash;
+      if (destination === window.location.pathname + window.location.search) return;
+      window.location.href = destination;
+    });
+
+    return () => {
+      document.removeEventListener("swUpdateFound", onUpdate);
+      document.removeEventListener("swUpdateDismissed", onDismiss);
+      unlisten();
+    };
+  }, [history]);
+}
+```
+
+Ce hook est à appeler **une seule fois**, au niveau du composant racine qui a accès au `Router` (ex. `App.tsx` ou le composant juste en dessous de `<BrowserRouter>`).
+
+---
+
+### 3. Nettoyer `useVersionCheck.ts`
+
+- Ajouter l'écoute de `visibilitychange` pour déclencher un check immédiat quand l'utilisateur revient sur l'onglet (les timers setInterval sont throttlés en arrière-plan par le navigateur).
+- Remplacer `fetch('/version.json?t=${Date.now()}')` par `fetch('/version.json', { cache: 'no-store' })` — plus propre, le `?t=` est redondant vu que le fichier est servi en `no-cache, no-store` côté S3.
+- Ajouter un guard `if (!res.ok) return` avant `res.json()` pour éviter de tenter de parser une page d'erreur CloudFront (HTML) comme du JSON.
+- Ajouter un `MIN_GAP` (ex. 30 secondes) pour éviter les rafales de fetch si `visibilitychange` + `setInterval` + `click` se chevauchent.
+- Le `checkOnClick` peut être conservé si présent, mais il doit respecter le `MIN_GAP`.
+
+---
+
+### 4. Filtrer les ChunkLoadError dans le système de crash reporting
+
+Dans `errorReportingService.ts`, avant d'envoyer une erreur, filtrer les erreurs de type chunk load pour ne pas polluer le crash reporting avec du bruit de déploiement qui se résout tout seul via le reload :
+
+Les patterns à filtrer (tous navigateurs) :
+- `Failed to fetch dynamically imported module` (Chrome)
+- `error loading dynamically imported module` (Firefox)
+- `Importing a module script failed` (Safari)
+- `Unable to preload CSS` (CSS chunk manquant)
+- `Cannot read properties of undefined (reading 'default')` **si** l'erreur provient d'un fichier `assets/index-*.js` (signature du chunk Vite)
+
+Ces erreurs doivent être soit ignorées, soit loggées avec un niveau `warn` distinct (pas `error`) pour conserver une trace sans polluer les alertes.
+
+---
+
+## Fichiers à modifier / créer
+
+| Fichier | Action |
+|---|---|
+| `index.html` | Modifier le listener `vite:preloadError` (garde anti-boucle) |
+| `src/hooks/useVersionCheck.ts` | Nettoyer (visibilitychange, no-store, MIN_GAP, guard ok) |
+| `src/hooks/useNavigationRefresh.ts` | Créer (hard refresh conditionnel à la navigation) |
+| `src/App.tsx` (ou composant racine) | Appeler `useNavigationRefresh()` une seule fois |
+| `src/services/errorReportingService.ts` | Filtrer les ChunkLoadError |
+
+---
+
+## Ce qu'il ne faut pas faire
+
+- Ne pas faire `window.location.reload()` à chaque changement de route — uniquement si `updatePending === true`.
+- Ne pas recréer un deuxième système de polling de version — `useVersionCheck` existant est la source de vérité.
+- Ne pas modifier `lazyWithRetry.ts` ni `chunkErrorUtils.ts` sauf si l'alignement de clé de l'étape 1 l'exige.
+- Ne pas supprimer la snackbar « Nouvelle version disponible » — elle reste utile pour les utilisateurs qui ne naviguent pas pendant une longue période.