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

docs/adr/004-types-duplication.md

@@ -0,0 +1,93 @@
+# ADR 004 — Types partagés par duplication contrôlée
+
+**Statut :** Accepté
+**Date :** 2026-04-17
+**Décideur :** Hermann
+
+---
+
+## Contexte
+
+Le frontend Expria et le backend Expria sont dans deux dépôts GitHub séparés (`expria-frontend` et `expria-backend`). Plusieurs types TypeScript doivent exister à l'identique des deux côtés :
+
+- `Plan` (`'free' | 'standard' | 'premium'`)
+- `PlanPermissions` (l'objet de l'objet `PLANS`)
+- `Production` (enregistrement d'une simulation)
+- `Report` (rapport de correction)
+- `ApiResponse<T>` (contrat de réponse normalisé)
+
+Sans synchronisation, ces types divergent, ce qui cause des bugs subtils (ex : un champ renommé dans le backend mais pas dans le frontend).
+
+## Options envisagées
+
+### Option A — Monorepo avec pnpm workspaces ou Turborepo
+
+- Avantages : un seul dépôt, types partagés via un package `@expria/types`, refactor global en une seule PR.
+- Inconvénients : restructuration massive (les dépôts actuels sont indépendants, chacun avec son propre CI/CD sur Render et Cloudflare Pages), courbe d'apprentissage pour un fondateur non-technique, complexité des commandes (`pnpm --filter frontend run dev`), incompatibilité avec le workflow Claude Code actuel (une session = un dépôt).
+
+### Option B — Package npm publié (`@expria/types`)
+
+- Avantages : types versionnés, installable comme n'importe quelle dépendance.
+- Inconvénients : publication sur npm (privé = $7/mois/dev, public = expose la structure du produit), versioning à gérer, friction de workflow (publier une nouvelle version à chaque changement).
+
+### Option C — Génération automatique via `tsc --declaration`
+
+- Avantages : les types sont dérivés directement du code backend, pas de divergence possible.
+- Inconvénients : pipeline de build à maintenir entre les deux dépôts, chaque modification backend nécessite un commit dans frontend pour régénérer les types, fragile au démarrage.
+
+### Option D — Duplication manuelle avec commentaire source
+
+- Avantages : zéro infrastructure, chaque dépôt reste autonome, compatible avec le workflow Claude Code actuel.
+- Inconvénients : discipline humaine requise pour synchroniser à chaque changement backend.
+
+## Décision
+
+**Option D** — duplication manuelle, avec règle de discipline stricte.
+
+### Format imposé
+
+Chaque fichier de types dupliqué commence par :
+
+```typescript
+// SOURCE OF TRUTH: expria-backend/src/types/<fichier>.ts
+// Synchronisé le : YYYY-MM-DD
+// Si ce fichier diverge du backend, le frontend doit être mis à jour immédiatement.
+```
+
+### Règle de synchronisation
+
+Tout changement de type dans le backend **doit** être répercuté dans le frontend dans le même commit logique (même jour, même session de travail). Cette règle est intégrée à `DEVELOPMENT_PRINCIPLES.md` frontend.
+
+### Liste des fichiers concernés
+
+- `src/entities/user/types.ts` ← `expria-backend/src/types/plan.ts`
+- `src/entities/production/types.ts` ← `expria-backend/src/types/production.ts`
+- `src/entities/report/types.ts` ← `expria-backend/src/types/report.ts`
+- `src/shared/types/api.ts` ← `expria-backend/src/types/api.ts`
+
+### Fichier critique particulier
+
+`src/entities/user/lib/access.ts` doit être **identique au bit près** à `expria-backend/src/lib/access.ts`. Cette règle est inscrite dans `ARCHITECTURE.md` §10 Règle 2 backend — on l'étend au frontend.
+
+## Conséquences
+
+**Positives :**
+- Zéro infrastructure, zéro outillage à maintenir.
+- Chaque dépôt reste autonome (cohérent avec le choix de dépôts séparés — `ARCHITECTURE.md` backend §3).
+- Workflow Claude Code inchangé (une session = un dépôt).
+- Coût zéro.
+
+**Négatives :**
+- Discipline humaine requise. Si la règle n'est pas respectée, divergence silencieuse possible.
+- Mitigation : ajouter dans `GOLDEN_DATASET.md` frontend un test de cohérence minimal — appeler `/plans/status` et vérifier que la structure retournée correspond aux types frontend.
+
+**À revisiter si :**
+- Un dev senior rejoint l'équipe et préfère un monorepo pnpm (décision à prendre avec lui).
+- Le projet stabilise ses types (6-12 mois de production sans changement de schéma). À ce moment, un package `@expria/types` devient viable.
+- Les divergences silencieuses causent plus de 2 bugs en production.
+
+## Références
+
+- `ARCHITECTURE.md` backend §3 (dépôts séparés)
+- `ARCHITECTURE.md` backend §10 Règle 2 (source de vérité unique pour `access.ts`)
+- `DEVELOPMENT_PRINCIPLES.md` frontend (règle de synchronisation à ajouter)