docs: ajout documentation de référence

2026-04-16 05:50:55 +03:00 · 2026-04-16 05:50:55 +03:00 · b06970c9ae
commit b06970c9ae
parent 1cb432401d
8 changed files with 2954 additions and 46 deletions
--- a/README.md
+++ b/README.md
@ -1,64 +1,169 @@
-expria-frontend
-Interface utilisateur d'Expria — Coach IA de préparation au TCF Canada.
-Plateforme SaaS francophone ciblant les candidats à l'immigration Express Entry
-(Algérie, Maroc, Cameroun).
-Stack technique
+# expria-backend

-React 18 + Vite — frontend pur, pas de logique serveur
-TypeScript — typage strict
-Tailwind CSS — styles utilitaires
-Supabase JS — authentification côté client uniquement
+API backend d'Expria — Coach IA de préparation au TCF Canada.
+Gère la logique métier, les permissions par plan, les corrections IA,
+les paiements Stripe, et le proxy WebSocket Gemini Live (T2 EO).
+
+## Stack technique
+
+- **Hono.js** — framework backend Node.js, TypeScript natif
+- **Node.js 20+**
+- **Supabase** — PostgreSQL + Auth (service role)
+- **DeepSeek** — corrections Expression Écrite et Orale
+- **Gemini** — transcription audio + proxy WebSocket T2 live
+- **Stripe** — paiements et gestion des abonnements
+- **Vitest** — tests automatisés
+
+## Documents de référence

-Documents de référence
 Lire ces fichiers avant toute modification :
-FichierContenudocs/DEVELOPMENT_PRINCIPLES.mdCycle de travail, règles, conventions — obligatoiredocs/ARCHITECTURE.mdStack, structure, flux de donnéesdocs/PLANS_TARIFAIRES.mdPlans Free / Standard / Premium et permissionsdocs/PARCOURS_UTILISATEURS.mdParcours exact de chaque type d'utilisateurdocs/GOLDEN_DATASET.mdTests manuels anti-régression
-Structure des dossiers
+
+| Fichier | Contenu |
+|---|---|
+| `docs/DEVELOPMENT_PRINCIPLES.md` | Cycle de travail, règles, conventions — **obligatoire** |
+| `docs/ARCHITECTURE.md` | Stack, structure, flux de données |
+| `docs/PLANS_TARIFAIRES.md` | Plans Free / Standard / Premium et permissions |
+| `docs/PARCOURS_UTILISATEURS.md` | Parcours exact de chaque type d'utilisateur |
+| `docs/GOLDEN_DATASET.md` | Tests manuels anti-régression |
+| `docs/TEST_ENVIRONMENT.md` | Comptes de test Supabase + scripts SQL |
+| `docs/TESTS_AUTOMATISES.md` | Tests Vitest — fonctions critiques |
+
+## Structure des dossiers
+
+```
 src/
-├── api/              # Fonctions d'appel API (une par domaine)
-├── components/       # Composants React réutilisables
-│   ├── ui/           # Composants génériques (Button, Modal, Badge)
-│   ├── simulation/   # Composants spécifiques aux simulations
-│   ├── rapport/      # Composants d'affichage des rapports
-│   ├── dashboard/    # Composants du dashboard utilisateur
-│   └── paywall/      # Composants de blocage / upgrade
-├── pages/            # Pages de l'application (une par route)
-├── hooks/            # Hooks React personnalisés
+├── routes/           # Définition des routes API (une par domaine)
+│   ├── auth.ts
+│   ├── simulations.ts
+│   ├── corrections.ts
+│   ├── plans.ts
+│   ├── stripe.ts
+│   └── t2live.ts     # WebSocket proxy Gemini Live
+├── controllers/      # Logique métier (une par domaine)
+├── middleware/
+│   ├── auth.ts       # Vérification JWT Supabase
+│   ├── plan.ts       # Vérification permissions par plan
+│   └── rateLimit.ts
 ├── lib/
 │   ├── access.ts     # Source de vérité des permissions par plan ⚠️
-│   ├── supabase.ts   # Client Supabase (auth uniquement)
-│   └── constants.ts  # Constantes globales
-└── types/            # Types TypeScript partagés
+│   ├── supabase.ts   # Client Supabase admin (service role)
+│   ├── deepseek.ts   # Client DeepSeek
+│   ├── gemini.ts     # Client Gemini
+│   └── stripe.ts     # Client Stripe
+├── types/            # Types TypeScript partagés
+└── index.ts          # Point d'entrée Hono
+```

-⚠️ src/lib/access.ts est la source de vérité unique des permissions par plan.
-Ce fichier doit rester identique à src/lib/access.ts dans expria-backend.
-Toute modification des plans tarifaires met ce fichier à jour en premier.
+> ⚠️ `src/lib/access.ts` est la source de vérité unique des permissions par plan.
+> Ce fichier doit rester identique à `src/lib/access.ts` dans `expria-frontend`.
+> Toute modification des plans tarifaires met ce fichier à jour en premier.

-Variables d'environnement
-Créer un fichier .env à la racine (ne jamais committer) :
-VITE_API_URL=http://localhost:3000          # URL backend en développement
-VITE_SUPABASE_URL=https://xxx.supabase.co
-VITE_SUPABASE_ANON_KEY=xxx                  # Clé publique uniquement
+## Variables d'environnement

-❌ Aucune clé privée ne doit apparaître dans ce fichier ou dans le code frontend.
+Créer un fichier `.env` à la racine (ne jamais committer) :

-Commandes
-bash# Installer les dépendances
+```
+# Supabase
+SUPABASE_URL=https://xxx.supabase.co
+SUPABASE_SERVICE_ROLE_KEY=xxx        # Clé privée — ne jamais exposer
+
+# APIs
+DEEPSEEK_API_KEY=xxx
+GEMINI_API_KEY=xxx                   # Ne jamais exposer côté frontend
+
+# Stripe
+STRIPE_SECRET_KEY=xxx
+STRIPE_WEBHOOK_SECRET=xxx
+STRIPE_PRICE_STANDARD=price_xxx      # price_id plan Standard
+STRIPE_PRICE_PREMIUM=price_xxx       # price_id plan Premium
+
+# Config
+PORT=3000
+APP_URL=https://expria.app
+API_URL=https://api.expria.app
+NODE_ENV=development
+```
+
+> ❌ Aucune de ces variables ne doit apparaître dans le dépôt `expria-frontend`.
+
+## Commandes
+
+```bash
+# Installer les dépendances
 npm install

-# Démarrer en développement
+# Démarrer en développement (avec rechargement automatique)
 npm run dev

 # Builder pour la production
 npm run build

-# Prévisualiser le build
-npm run preview
-Déploiement
-Plateforme : Cloudflare Pages
-Déploiement : manuel via CLI
-bashnpm run build
-npx wrangler pages deploy dist --project-name=expria
-Domaine : expria.app
-Dépôt lié
-Backend : codeberg.org/germannoff/expria-backend
+# Démarrer en production
+npm start

+# Lancer les tests automatisés
+npm run test
+
+# Lancer les tests en mode watch
+npm run test:watch
+
+# Générer un rapport de couverture
+npm run test:coverage
+```
+
+## Tests automatisés
+
+41 tests Vitest couvrant les 6 fonctions critiques :
+
+```bash
+npm run test
+# Résultat attendu : 41/41 passés, 0 échec
+```
+
+> ⚠️ Les tests doivent être verts avant ET après chaque session de développement.
+> Un test rouge = régression détectée = ne pas continuer.
+
+Voir `docs/TESTS_AUTOMATISES.md` pour le détail des tests.
+
+## Environnement de test
+
+4 comptes Supabase préconfigurés pour tester tous les parcours utilisateur
+sans passer par Stripe.
+
+Voir `docs/TEST_ENVIRONMENT.md` pour les scripts SQL de création et réinitialisation.
+
+## Déploiement
+
+Plateforme : **Render** (Frankfurt EU)
+Déploiement : manuel via dashboard ou CLI
+
+```bash
+# Via Render CLI
+render deploy
+
+# Via dashboard Render
+# → Manual Deploy → Deploy latest commit
+```
+
+Domaine : `api.expria.app`
+
+## Routes API
+
+```
+POST   /auth/verify-token
+POST   /simulations
+GET    /simulations/:id
+GET    /simulations
+POST   /corrections/ee
+POST   /corrections/eo
+GET    /plans/status
+POST   /plans/upgrade
+POST   /plans/upgrade-prorata
+POST   /stripe/checkout
+POST   /stripe/webhook
+WS     /t2/live
+```
+
+## Dépôt lié
+
+Frontend : `https://codeberg.org/Hermann_Kitio/expria-frontend`