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