capitalisation: intégration ~60 entrées RL799_V2 (triage 2026-05-02)

Triage du 95_a_capitaliser.md (~75 propositions) : - 60 entrées intégrées dans knowledge/ (backend, frontend, workflow) - 4 nouveaux fichiers : backend/patterns/tests.md, backend/risques/tests.md, frontend/patterns/general.md, workflow/patterns/general.md - 6 doublons rejetés - Mise à jour des READMEs index pour refléter les nouvelles entrées - 95_a_capitaliser.md restauré à sa structure initiale - 40_decisions_et_archi.md : décision mono-tenant déployable vs SaaS multi-tenant - 90_debug_et_postmortem.md : sub-agents Write indisponible, effet iceberg CI, prisma migrate diffs cosmétiques Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-18 08:18:15 +02:00 · 2026-05-02 22:12:44 +02:00
parent 02ad0de258
commit b3417ad77b
31 changed files with 5370 additions and 12 deletions
--- a/knowledge/frontend/risques/general.md
+++ b/knowledge/frontend/risques/general.md
@@ -319,3 +319,474 @@ Poser `role="menu"` / `role="menuitem"` implique obligatoirement :
 - Contexte technique : PWA / install prompt — RL799_V2 18-04-2026

 ---
+
+<a id="risque-cache-pwa-soft-delete-fuite"></a>
+## Cache offline PWA + soft-delete — invalidation diff-based scopée
+
+### Risques
+
+- Une PWA qui cache des blobs en IndexedDB pour offline reading **ne reçoit aucun signal automatique** quand un document est soft-deleted côté serveur
+- Le contenu reste lisible hors-ligne indéfiniment. Pour des données réglementaires ou sensibles, c'est un gap de sécurité non négligeable
+
+### Symptômes
+
+- Document soft-deleted en base, encore consultable offline par les utilisateurs qui l'ont mis en cache
+- Aucun mécanisme automatique de purge
+
+### Bonnes pratiques / mitigations
+
+**Mitigation V1 (best-effort, diff-based)** au prochain `loadEntries` online :
+
+1. Lire la liste serveur courante (filtrée `deletedAt IS NULL`)
+2. Lire les IDs cachés localement **scopés au même périmètre** (type+grade) — sinon on supprime à tort un doc d'un autre onglet
+3. Diff : `cached - server = soft-deleted` → `removeCachedDocument(id)` pour chaque
+
+```typescript
+const bustCachedIfMissing = async (candidateIds: string[], serverIds: Set<string>) => {
+  for (const id of candidateIds) {
+    if (!serverIds.has(id)) await removeCachedDocument(id);
+  }
+};
+```
+
+**Mitigation V2 (push server-initiated)** : Service Worker abonné à un canal (postMessage / WebSocket / SSE), serveur publie `{ type: 'document-soft-deleted', id }` sur soft-delete, SW intercepte et fait `caches.delete()` immédiat. Coût : infra push + gestion connectivité partielle. À garder en backlog si le risque devient critique (audit GDPR).
+
+**Tests recommandés** :
+- doc caché + recharge avec serveur qui omet ce doc → assert `removeCachedDocument` appelé
+- doc caché + serveur qui retourne le doc → assert pas d'effet (non-régression)
+- doc caché pour scope `rituels` + recharge sur scope `mementos` qui omet ce doc → assert pas d'effet (scope isolation)
+
+- Contexte technique : PWA / IndexedDB — RL799_V2 20-04-2026
+
+---
+
+<a id="risque-duplication-focus-parent-modal"></a>
+## Duplication parent ↔ modal de la capture de focus
+
+### Risques
+
+- Quand un composant modal implémente correctement le pattern a11y `previousActiveElement` (capture à `onMounted`, restitution à `close`/`submit`), le composant parent **ne doit PAS** stocker un `lastTrigger` en parallèle
+- Code mort avec commentaire trompeur : un lecteur qui cherche à comprendre le flux focus va s'y perdre
+
+### Symptômes
+
+- Le parent a une ref `lastFabTrigger` / `lastTrigger` écrite au clic du trigger
+- Elle n'est **jamais lue** — le commentaire prétend "pour restitution du focus par la modal", mais la modal a son propre mécanisme
+
+### Bonnes pratiques / mitigations
+
+- **Une seule responsabilité** pour la restitution du focus : la modal
+- Le parent se contente d'ouvrir la modal (`uploadModalOpen.value = true`)
+- Le parent ne capture le focus QUE si la modal ne le fait pas (cas d'un overlay maison sans pattern `previousActiveElement`)
+- **Repérage en code review** : `grep -n "lastTrigger\|previousActive" components/ pages/` → s'il y a des occurrences dans BOTH un parent et une modal du même flux, c'est le signal
+
+- Contexte technique : Vue 3 / a11y modales — RL799_V2 20-04-2026
+
+---
+
+<a id="risque-touch-action-none-card-mobile"></a>
+## `touch-action: none` sur card mobile bloque scroll vertical
+
+### Risques
+
+- Une card mobile gérant un swipe horizontal avec `touch-action: none` capture **tout** le toucher, laissant le JS gérer le scroll vertical
+- Le JS détecte scroll vs swipe via un seuil mais doit **libérer** l'événement après l'avoir analysé → un délai imperceptible s'installe, le scroll vertical devient saccadé et souvent ignoré
+- L'utilisateur trouve la liste "inscrollable" quand son pouce touche directement les cards
+
+### Symptômes
+
+- Poser le pouce sur une card puis scroller ne marche qu'une fois sur 20
+- Scroll OK dans les marges vides à côté
+- Aucune erreur console
+
+### Bonnes pratiques / mitigations
+
+```css
+/* AVANT — bug : scroll vertical capturé */
+.member-card {
+  touch-action: none;
+}
+
+/* APRÈS — scroll natif OK, swipe horizontal toujours fonctionnel */
+.member-card {
+  touch-action: pan-y;
+}
+```
+
+Combiné avec un handler JS qui `preventDefault` uniquement sur mouvement horizontal significatif (> 10 px) :
+
+```typescript
+if (Math.abs(deltaX) > 10 && Math.abs(deltaX) > Math.abs(deltaY)) {
+  event.preventDefault();
+}
+```
+
+**Règle** :
+- Card qui gère swipe horizontal ET scroll vertical : `touch-action: pan-y` (le navigateur gère nativement le scroll vertical, seul l'axe horizontal est laissé au JS)
+- Card qui ne gère QUE du pan/zoom custom (rare) : `touch-action: none` peut se justifier
+- Tous les autres cas : laisser la valeur par défaut (`auto`)
+
+**Repérage en code review** : `grep -rn "touch-action: none" components/` → chaque occurrence est suspecte.
+
+- Contexte technique : CSS / mobile — RL799_V2 21-04-2026
+
+---
+
+<a id="risque-button-wrapper-card-color-inherit"></a>
+## `<button>` wrapper card — toujours `color: inherit` (reset user-agent)
+
+### Risques
+
+- Quand on utilise un `<button>` comme wrapper cliquable d'une card (pattern idiomatique pour l'a11y clavier), il hérite du `color` user-agent par défaut
+- Sur certains setups (Safari/dark mode notamment), ce `color` peut être bleu — le texte enfant hérite et contamine titres et paragraphes qui devraient prendre la couleur du thème
+
+### Symptômes
+
+- Titre de card en bleu sur fond sombre alors que le thème prévoit de l'or
+- Bug non visible en dev light mode sur Chrome — apparaît uniquement sur certains setups → difficile à reproduire
+
+### Bonnes pratiques / mitigations
+
+```css
+.my-card-button {
+  /* reset user-agent */
+  color: inherit;
+  font-family: inherit;
+  border: 0;
+  background: transparent;
+  /* … */
+}
+```
+
+**Règle** : tout `<button>` qui wrappe du contenu stylé par le thème (card, liste, ligne de tableau) doit reset `color`, `font-family`, `font-size`, `border`, `background`. C'est un bootstrap user-agent minimal à prévoir dans tout design system.
+
+**Alternative** : `<div role="button" tabindex="0">` avec `@keydown.enter/space`. Plus verbeux, mais évite les resets. Pattern valide si l'équipe est à l'aise avec les implications a11y.
+
+- Contexte technique : CSS / a11y — RL799_V2 21-04-2026
+
+---
+
+<a id="risque-erreur-silencieuse-4-etats"></a>
+## Erreur silencieuse = blanc indistinguable de "aucune donnée" — 4 états distincts (loading / empty / error / forbidden)
+
+### Risques
+
+- Un composant qui affiche le résultat d'un fetch sans distinguer ses 4 états produit du **blanc** dans 3 cas sur 4 — l'utilisateur ne peut pas savoir si la donnée est en chargement, légitimement vide, en erreur réseau, ou refusée par RBAC
+- Sur les flows critiques (rituel, opérations sensibles), un blanc silencieux est inacceptable : l'utilisateur prend des décisions sur la base de l'affichage
+
+### Symptômes
+
+- Plusieurs cards d'une vue qui auto-fetchent et tombent toutes en `[]` côté front quand l'API renvoie 403 — affichage indistinguable de "vide légitime"
+- Toast générique "Une erreur est survenue" sans corrélation avec un retry actionnable
+
+### Bonnes pratiques / mitigations
+
+Tout composant qui fetch une ressource doit avoir **4 états distincts** dans son rendu :
+
+1. **Loading** : skeleton, spinner, ou texte explicite (« Chargement… »)
+2. **Empty (donnée légitimement vide)** : message explicite *« Aucune donnée enregistrée pour … »*
+3. **Error (réseau / serveur)** : message + bouton retry. Ne jamais se contenter d'un blanc
+4. **Forbidden (403)** : message explicite *« Vous n'avez pas accès à cette donnée »* + suggestion d'action (recharger / contacter admin)
+
+Le frontend doit savoir **distinguer 403** des autres erreurs au niveau de son service HTTP, et propager l'info au composant. Ne pas traiter `!response.ok` en bloc avec un message générique.
+
+```typescript
+export const getXxx = async (id: string) => {
+  const response = await apiFetch(`/api/xxx/${id}`);
+  if (response.status === 403) throw new ForbiddenError(...);
+  if (response.status === 404) throw new NotFoundError(...);
+  if (!response.ok) throw new Error(await parseError(response));
+  return (await response.json()).data;
+};
+```
+
+Le composant catche les types d'erreur et choisit le rendu approprié.
+
+- Contexte technique : Vue 3 / fetch — RL799_V2 27-04-2026
+
+---
+
+<a id="risque-service-worker-non-secure-context"></a>
+## Service Worker invisible en accès non-secure (HTTP via IP réseau)
+
+### Risques
+
+- Les Service Workers exigent un [secure context](https://developer.mozilla.org/en-US/docs/Web/Security/Secure_Contexts) — HTTPS strict, OU URL `http://localhost:*` ou `http://127.0.0.1:*`
+- Un accès via IP réseau en HTTP (Tailscale `100.x.x.x`, LAN `192.168.x.x`) est non-secure → `navigator.serviceWorker` est `undefined` → la PWA fonctionne en mode "navigateur classique" mais sans cache offline, sans push, sans badge, sans installation
+- Les tests E2E en Tailscale loupent silencieusement les régressions SW
+
+### Symptômes
+
+- `navigator.serviceWorker.register('/sw.js')` lève `Cannot read properties of undefined (reading 'register')`
+- DevTools > Application > Service Workers ne montre rien
+- Tests "ça marche en LAN" qui ne reflètent pas la prod HTTPS
+
+### Bonnes pratiques / mitigations
+
+```javascript
+// Détection
+console.log(window.isSecureContext, location.protocol, location.hostname);
+// true "https:" "..." → OK
+// true "http:" "localhost" → OK
+// false "http:" "192.168.1.42" → SW désactivé
+```
+
+Stratégies par contexte :
+
+1. **Test local** : utiliser `http://localhost:<port>` strict (jamais l'IP, même en LAN)
+2. **Test réseau / mobile** : reverse proxy HTTPS (Caddy/Traefik avec Let's Encrypt, ou `tailscale cert` pour le magicDNS Tailscale)
+3. **Préview Vite** : `vite preview --https` avec un certificat auto-signé (acceptable en dev test)
+
+**Préventif** :
+- documenter dans le README projet que le SW exige HTTPS/localhost
+- en CI E2E, toujours utiliser `localhost` (le webServer Playwright tourne sur `localhost` par défaut)
+- ne PAS supposer qu'un test "ça marche en LAN" reflète la prod HTTPS
+
+- Contexte technique : PWA / Service Worker — RL799_V2 28-04-2026
+
+---
+
+<a id="risque-vite-pwa-bascule-strategies-runtime-caching"></a>
+## Vite-plugin-pwa : bascule `generateSW` → `injectManifest` rend `runtimeCaching` inerte
+
+### Risques
+
+- En mode `injectManifest`, Vite PWA n'injecte PAS de runtime workbox — il bundle le `src/sw.ts` fourni tel quel
+- Toute la config `workbox.*` du `vite.config.ts` (sauf `globPatterns`/`globIgnores` déplacés sous `injectManifest.*`) est ignorée silencieusement, sans warning
+- Régression directe : leak de cookies API en cache, contenu sensible en cache, 404 transformés en `index.html`
+
+### Symptômes
+
+- Après bascule, les routes runtime configurées dans `workbox.runtimeCaching` n'ont plus aucun effet
+- Le build passe, aucune erreur visible, mais en DevTools > Application > Service Worker on ne voit pas les routes attendues
+
+### Bonnes pratiques / mitigations
+
+Détection : examiner `dist/sw.js` après build — chercher des strings clés (`/api/`, `uploads`, `manifest.webmanifest`, `addEventListener`). Si elles sont absentes du SW custom, c'est qu'on a perdu la protection.
+
+**Mitigation** : RÉIMPLÉMENTER À LA MAIN dans `src/sw.ts` toutes les routes runtime, denylist, et cleanup :
+
+```typescript
+import { precacheAndRoute, cleanupOutdatedCaches } from 'workbox-precaching';
+import { registerRoute, NavigationRoute } from 'workbox-routing';
+import { NetworkOnly, NetworkFirst } from 'workbox-strategies';
+import { ExpirationPlugin } from 'workbox-expiration';
+
+cleanupOutdatedCaches();
+precacheAndRoute(self.__WB_MANIFEST);
+
+registerRoute(({ url }) => url.pathname.startsWith('/api/'), new NetworkOnly());
+registerRoute(({ url }) => url.pathname.startsWith('/uploads/'), new NetworkOnly());
+registerRoute(
+  ({ url }) => url.pathname === '/manifest.webmanifest',
+  new NetworkFirst({
+    cacheName: 'manifest-cache',
+    plugins: [new ExpirationPlugin({ maxAgeSeconds: 300, maxEntries: 1 })],
+  }),
+);
+
+registerRoute(
+  new NavigationRoute(async () => { /* fallback handler */ }, {
+    denylist: [/^\/api\//, /^\/uploads\//, /^\/manifest\.webmanifest$/],
+  }),
+);
+```
+
+**Vérifications obligatoires post-bascule** (DevTools sur build/preview) :
+
+1. Application > Service Worker : `sw.js` activé
+2. Network : `POST /api/auth/login` → pas de "(from ServiceWorker)", pas de cache
+3. Network : GET `/uploads/foo.pdf` → réseau direct
+4. Network mode Offline : navigation `/page` → fallback `index.html` ; `/api/foo` → erreur réseau (PAS index.html)
+5. Déploiement v2 : ancien cache purgé après activation
+
+`setCatchHandler` ne suffit PAS à remplacer `navigateFallback` — il ne se déclenche que si une route enregistrée throw. Pour le navigation fallback, utiliser `NavigationRoute` explicitement.
+
+- Contexte technique : Vite / vite-plugin-pwa / Workbox — RL799_V2 28-04-2026
+
+---
+
+<a id="risque-ts-strict-uint8array-buffersource"></a>
+## TS strict — `Uint8Array<ArrayBufferLike>` non assignable à `BufferSource`
+
+### Risques
+
+- TS 5.7+ avec lib DOM récente paramètre `Uint8Array` par défaut sur `ArrayBufferLike` (qui inclut `SharedArrayBuffer`)
+- Beaucoup d'APIs DOM (Push API, WebCrypto certaines surfaces) attendent un `BufferSource` strict avec `buffer: ArrayBuffer` — d'où une erreur TS au build
+
+### Symptômes
+
+```
+Type 'Uint8Array<ArrayBufferLike>' is not assignable to type 'BufferSource'.
+  Types of property 'buffer' are incompatible.
+    Type 'ArrayBufferLike' is not assignable to type 'ArrayBuffer'.
+      Type 'SharedArrayBuffer' is missing the following properties from type 'ArrayBuffer'…
+```
+
+L'erreur est au build, pas au runtime (le code marche en JS).
+
+### Bonnes pratiques / mitigations
+
+Créer explicitement un `ArrayBuffer` strict, puis remplir via une vue `Uint8Array` :
+
+```typescript
+// ❌ Ne compile pas en TS strict
+const urlBase64ToUint8Array = (s: string): Uint8Array => {
+  const raw = atob(s.replace(/-/g, '+').replace(/_/g, '/'));
+  const out = new Uint8Array(raw.length);
+  for (let i = 0; i < raw.length; i++) out[i] = raw.charCodeAt(i);
+  return out;
+};
+
+// ✅ Compile et fonctionne identiquement
+const urlBase64ToArrayBuffer = (s: string): ArrayBuffer => {
+  const raw = atob(s.replace(/-/g, '+').replace(/_/g, '/'));
+  const buf = new ArrayBuffer(raw.length);
+  const view = new Uint8Array(buf);
+  for (let i = 0; i < raw.length; i++) view[i] = raw.charCodeAt(i);
+  return buf;
+};
+```
+
+**Alternative déconseillée** : `as ArrayBuffer` cast — masque le problème, peut rater une vraie incompatibilité si la lib DOM évolue.
+
+- Contexte technique : TypeScript 5.x / lib DOM — RL799_V2 28-04-2026
+
+---
+
+<a id="risque-safe-areas-ios-viewport-fit-cover"></a>
+## Safe-areas iOS — `viewport-fit=cover` indispensable
+
+### Risques
+
+- Sur iPhone Pro/Max (notch + home indicator + Dynamic Island), `padding-top: env(safe-area-inset-top)` ou `padding-bottom: env(safe-area-inset-bottom)` retourne **0** sans `<meta viewport content="… viewport-fit=cover">`
+- Le développeur conclut à tort que le pattern ne fonctionne pas, alors qu'il manque juste l'opt-in
+
+### Symptômes
+
+- Header fixed rogné par le notch
+- Nav bottom rognée par le home indicator
+- `env(safe-area-inset-*)` retourne 0 sur iPhone Pro+
+
+### Bonnes pratiques / mitigations
+
+**Pattern complet (3 endroits) à appliquer ensemble** :
+
+```html
+<!-- 1) index.html — opt-in safe-areas -->
+<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover">
+```
+
+```css
+/* 2) Header sticky : top + safe-area-inset-top */
+.app-header {
+  position: fixed;
+  top: 0;
+  padding-top: env(safe-area-inset-top);
+  height: calc(var(--size-header-height) + env(safe-area-inset-top));
+}
+
+/* 3) Nav bottom : bottom + safe-area-inset-bottom + safe-area-inset-left/right */
+.app-nav {
+  position: fixed;
+  bottom: 0;
+  padding-bottom: env(safe-area-inset-bottom);
+  padding-left: env(safe-area-inset-left);
+  padding-right: env(safe-area-inset-right);
+  height: calc(var(--size-nav-height) + env(safe-area-inset-bottom));
+}
+
+/* FAB / menu flottant : bottom au-dessus de la nav + safe-area + offset */
+.fab {
+  bottom: calc(var(--size-nav-height) + env(safe-area-inset-bottom) + 16px);
+  /* `max()` empêche les boutons d'être collés au bord rond du device */
+  right: max(16px, env(safe-area-inset-right));
+}
+```
+
+**Règle de débogage** : si `env(safe-area-inset-bottom)` semble retourner 0 sur iPhone Pro+, **vérifier `<meta viewport>` AVANT de chercher ailleurs**. C'est presque toujours la cause.
+
+`safe-area-inset-left` et `safe-area-inset-right` ne sont non-nuls qu'en mode paysage (notch latéral). Garder le `padding-left/right` quand même → no-op en portrait, fix en paysage.
+
+- Contexte technique : CSS / iOS — RL799_V2 02-05-2026
+
+---
+
+<a id="risque-input-date-safari-ios-min-width"></a>
+## `<input type="date">` Safari iOS — `appearance: none` + `min-width: 0` + `min-height` obligatoires
+
+### Risques
+
+- Sur Safari iOS (et Chrome iOS car webkit sous-jacent), un `<input type="date">` ou `datetime-local` :
+  - déborde de son conteneur sur la droite (largeur intrinsèque > 100 %)
+  - apparaît plus mince que les autres inputs (hauteur intrinsèque différente)
+  - affiche un styling natif iOS qui casse le design system
+
+### Symptômes
+
+- `width: 100%` ne suffit pas — la largeur intrinsèque écrase la contrainte
+- Bug non reproductible sur Chrome desktop, visible uniquement sur iPhone réel ou Safari Responsive Design Mode
+
+### Bonnes pratiques / mitigations
+
+```css
+input[type="date"],
+input[type="datetime-local"],
+input[type="time"] {
+  appearance: none;          /* neutralise le styling natif */
+  -webkit-appearance: none;  /* Safari iOS — ne PAS oublier */
+  min-width: 0;              /* permet à width: 100% de gagner */
+  min-height: 48px;          /* aligne avec les autres inputs */
+}
+```
+
+**Les 4 propriétés sont nécessaires** :
+
+- `appearance: none` seul : le styling natif disparaît mais la largeur intrinsèque reste → débordement
+- `min-width: 0` seul : le styling natif reste, on a juste cassé sa hauteur
+- `min-height: 48px` : nécessaire pour homogénéiser avec les inputs text classiques
+- `-webkit-appearance: none` : redondant en théorie avec `appearance: none` mais nécessaire en pratique sur certaines versions Safari iOS
+
+- Contexte technique : CSS / Safari iOS — RL799_V2 01-05-2026
+
+---
+
+<a id="risque-fieldset-legend-flex-grid"></a>
+## `<fieldset>` / `<legend>` cassent un layout flex inline
+
+### Risques
+
+- Pour un champ "label + valeur inline" (ex : `Grade [GradeBadge]` sur la même ligne), le réflexe sémantique est `<fieldset>` + `<legend>`
+- `<legend>` a un comportement natif particulier : interrompt visuellement le `border` du fieldset, son `display` est traité spécialement, il ne se comporte pas comme un enfant flex/grid normal
+- Le legend prend toute la largeur, l'input passe en dessous, impossible de les aligner sans hacks `position: absolute`
+
+### Symptômes
+
+- `<fieldset style="display: flex">` avec `<legend>` + `<input>` qui ne s'alignent pas sur la même ligne
+
+### Bonnes pratiques / mitigations
+
+Pour un groupe de champs **avec layout custom** (flex/grid inline), utiliser `<div>` + `<span class="label">` + le champ :
+
+```html
+<!-- ❌ Layout cassé : legend ne se comporte pas comme un enfant flex -->
+<fieldset class="field-inline">
+  <legend>Grade</legend>
+  <GradeBadge :grade="grade" />
+</fieldset>
+
+<!-- ✅ Layout custom OK : div + span — perte sémantique mineure
+     compensée par aria-labelledby si besoin -->
+<div class="field-inline">
+  <span class="field-inline__label" id="grade-label">Grade</span>
+  <GradeBadge :grade="grade" aria-labelledby="grade-label" />
+</div>
+```
+
+Garder `<fieldset>/<legend>` uniquement quand on accepte le rendu natif (groupe vertical avec border + legend qui chevauche le border supérieur — pattern formulaire admin classique).
+
+**Trade-off à assumer** : `<fieldset>` apporte une sémantique a11y (groupe de champs liés). En remplaçant par `<div>`, on peut compenser via `role="group" aria-labelledby="..."` si le besoin d'a11y est fort. Pour un simple label+badge inline, c'est rarement nécessaire.
+
+- Contexte technique : HTML / a11y / CSS — RL799_V2 02-05-2026
+
+---