expria-backend

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

Lire ces fichiers avant toute modification :

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/
├── 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 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-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) :

# 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

# Installer les dépendances
npm install

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

# Builder pour la production
npm run build

# 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 :

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

# 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