docs: ajouter ONBOARDING, SECURITY, CHANGELOG, ADR 001-006

2026-04-17 18:35:15 +03:00 · 2026-04-17 18:35:15 +03:00 · 52b8e9d011
commit 52b8e9d011
parent 28c9c08d31
9 changed files with 1380 additions and 0 deletions
--- a/docs/adr/006-stack-versions-2026.md
+++ b/docs/adr/006-stack-versions-2026.md
@ -0,0 +1,160 @@
+# ADR 006 — Stack frontend : versions 2026 (React 19, Vite 8, TypeScript 6, Tailwind 4, RR7)
+
+**Statut :** Accepté
+**Date :** 2026-04-17
+**Décideur :** Hermann
+**Contexte :** Révélé par l'état des lieux Claude Code au démarrage du Sprint 0 frontend
+
+---
+
+## Contexte
+
+La première version d'`ARCHITECTURE.md` §2 listait une stack basée sur les versions "connues stables" :
+
+- React 18
+- Vite 5
+- TypeScript 5
+- Tailwind 3
+- React Router v6
+
+L'état des lieux effectué par Claude Code au démarrage du Sprint 0 (2026-04-17) a révélé que le scaffold installé plusieurs semaines auparavant utilisait des versions plus récentes :
+
+- React 19.2.4
+- Vite 8.0.4
+- TypeScript 6.0.2
+- Tailwind 4.2.2
+- React Router v7.14.1
+
+Cette divergence doit être résolue : soit downgrader le scaffold, soit mettre à jour la documentation.
+
+## Options envisagées
+
+### Option A — Downgrader vers les versions de la doc originale
+
+Aligner le scaffold sur React 18, Vite 5, TypeScript 5, Tailwind 3, React Router v6.
+
+- **Avantages :** documentation historique respectée, versions "éprouvées" en production.
+- **Inconvénients :**
+  - Casse un `node_modules` qui fonctionne
+  - Perd l'optimisation du compilateur React 19 (Actions, useOptimistic)
+  - Perd le moteur Oxide de Tailwind 4 (builds 3,5x plus rapides)
+  - Perd le typage strict amélioré de TypeScript 6
+  - Downgrade effectué pour des raisons qui n'existent plus (les versions récentes sont matures en avril 2026)
+
+### Option B — Mettre à jour la documentation
+
+Accepter les versions installées et mettre à jour `ARCHITECTURE.md §2` pour refléter la réalité.
+
+- **Avantages :**
+  - Préserve le travail de scaffold déjà fait
+  - Bénéficie des améliorations de performance des versions récentes
+  - Écosystème mature : shadcn/ui supporte complètement Tailwind 4 et React 19 depuis début 2025
+  - Alignement avec l'écosystème 2026 (les nouveaux tutoriels, docs, et ressources communautaires supposent ces versions)
+- **Inconvénients :**
+  - Versions légèrement plus récentes = moins de StackOverflow disponible pour les cas exotiques
+  - Mitigation : Claude Opus 4.7 connaît bien ces versions (cf. knowledge cutoff janvier 2026)
+
+### Option C — Hybride
+
+Garder React 19, Vite 8, TypeScript 6 mais downgrader Tailwind 4 → 3 pour "compatibilité shadcn/ui classique".
+
+- **Avantages :** apparemment plus prudent.
+- **Inconvénients :** injustifié depuis que shadcn/ui supporte complètement Tailwind 4 avec configuration CSS-first via `@theme`. Ajoute de la complexité sans bénéfice.
+
+## Décision
+
+**Option B** — accepter les versions installées et mettre à jour la documentation.
+
+### Stack frontend officielle au 2026-04-17
+
+| Couche | Version | Notes |
+|---|---|---|
+| React | 19.2.x | Server Components N/A (SPA pur), Actions et useOptimistic disponibles |
+| React DOM | 19.2.x | |
+| Vite | 8.0.x | Moteur Rolldown stable, config simplifiée |
+| TypeScript | 6.0.x | Typage strict activé (voir tsconfig.app.json) |
+| Tailwind CSS | 4.2.x | Configuration CSS-first via `@theme`, pas de `tailwind.config.ts` |
+| `@tailwindcss/vite` | 4.2.x | Plugin Vite officiel (préféré au plugin PostCSS) |
+| React Router | v7.14.x | Compatible API v6, data loaders disponibles |
+| Supabase JS | 2.103.x | |
+
+### Dépendances à ajouter lors du scaffold
+
+| Package | Rôle | Cf. ADR |
+|---|---|---|
+| `@tanstack/react-query` | Cache serveur, refetch, mutations | ARCHITECTURE.md §2 |
+| `zod` | Validation des inputs formulaires | SECURITY.md SEC-04 |
+| `react-markdown` | Rendu sécurisé des rapports IA | SECURITY.md SEC-05 |
+| `class-variance-authority`, `clsx`, `tailwind-merge` | Utilitaires shadcn/ui | — |
+| `lucide-react` | Icônes (standard shadcn/ui) | — |
+| Packages `@radix-ui/react-*` | Primitives shadcn/ui (installés à la demande) | — |
+| `@sentry/react` | Monitoring | TECH_DEBT.md FTD-07 (après MVP) |
+
+### Dépendances de développement
+
+| Package | Rôle |
+|---|---|
+| `vitest` | Tests unitaires |
+| `@vitest/coverage-v8` | Couverture |
+| `@testing-library/react` | Tests React |
+| `@testing-library/jest-dom` | Matchers DOM |
+| `@testing-library/user-event` | Simulation user |
+| `jsdom` | Environnement DOM pour Vitest |
+| `prettier` | Formatage |
+| `eslint-config-prettier` | Intégration ESLint ↔ Prettier |
+
+### Configuration Tailwind 4
+
+Pas de `tailwind.config.ts`. La configuration se fait exclusivement dans `src/index.css` via les directives :
+
+```css
+@import "tailwindcss";
+
+@theme {
+  --color-primary: #1B4FD8;           /* Couleur brand Expria */
+  --font-sans: "Plus Jakarta Sans", system-ui, sans-serif;
+  /* Autres variables de thème */
+}
+```
+
+### shadcn/ui avec Tailwind 4
+
+La CLI shadcn/ui supporte Tailwind 4 depuis début 2025 :
+
+```bash
+npx shadcn@latest init
+npx shadcn@latest add button dialog form
+```
+
+Les composants générés utilisent les conventions Tailwind 4 (pas de `forwardRef`, attributs `data-slot`). Le fichier de configuration reste `components.json` à la racine.
+
+## Conséquences
+
+**Positives :**
+- Pas de perte de travail sur le scaffold existant
+- Performances optimales (build Tailwind 4 : microsecondes sur builds incrémentaux)
+- Stack aligné sur l'écosystème 2026 — facile pour un dev externe qui arrivera
+- Compilateur React 19 apporte des optimisations gratuites
+
+**Négatives :**
+- Les versions récentes peuvent avoir quelques bugs non encore découverts. Mitigation : mise à jour ponctuelle vers la dernière version patch en cas de bug signalé (ex : 19.2.4 → 19.2.5).
+- Si un dev arrive avec une expertise sur React 17/18 uniquement, courbe d'apprentissage légère. Mitigation : `ONBOARDING.md` liste les ressources officielles pour React 19 et Tailwind 4.
+
+**À revisiter si :**
+- Une faille de sécurité critique apparaît dans une version spécifique
+- Une incompatibilité bloquante est découverte entre deux packages (peu probable en avril 2026)
+
+## Actions de mise en cohérence
+
+1. Mettre à jour `ARCHITECTURE.md §2` avec les versions ci-dessus (réalisé en session actuelle)
+2. Mettre à jour `ONBOARDING.md` pour référencer React 19 et Tailwind 4 dans les ressources (à faire)
+3. Aucune action sur `TESTS_AUTOMATISES.md` — Vitest fonctionne identiquement
+4. Aucune action sur les ADRs 001-005 — ils ne référencent pas de versions précises
+
+## Références
+
+- État des lieux Claude Code du 2026-04-17
+- [shadcn/ui Tailwind v4](https://ui.shadcn.com/docs/tailwind-v4) — support officiel confirmé
+- [React 19 Upgrade Guide](https://react.dev/blog/2024/04/25/react-19)
+- [Tailwind CSS v4.0](https://tailwindcss.com/blog/tailwindcss-v4)
+- `ARCHITECTURE.md` §2 (mis à jour en parallèle)