169 lines
4.6 KiB
Markdown
169 lines
4.6 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
# 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 :
|
|
|
|
```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`
|