# Dev setup — environnement local

> Version : 0.1 · 2026-05-06

Tout ce qu'il faut pour faire tourner Rubis en local : services backing (Postgres, Redis, MinIO, Mailhog) + l'API + le SPA.

## Prérequis

- **Node 22+** (cf. `engines` dans `package.json`)
- **pnpm 10+**
- **Docker + Docker Compose v2** (pour les services backing)

## 1. Services backing — docker-compose.dev.yml

Un seul fichier à la racine fait tourner les 4 services dont l'API a besoin :

| Service | Port hôte | Port interne | Notes |
|---|---|---|---|
| **Postgres** | 5433 | 5432 | DB applicative `rubis_dev` (user `rubis` / pass `rubis`) |
| **Redis** | 6380 | 6379 | Backend BullMQ + cache |
| **MinIO API** | 9100 | 9000 | S3-compatible. Bucket `rubis-invoices` créé au boot. |
| **MinIO Console** | 9101 | 9001 | UI web : http://localhost:9101 — login `rubis` / `rubis-dev-secret` |
| **Mailpit SMTP** | 1025 | 1025 | Catch-all pour les emails locaux |
| **Mailpit UI** | 8025 | 8025 | UI web : http://localhost:8025 |

Les ports hôte sont **décalés** (5433, 6380, 9100…) pour éviter les collisions avec un Postgres/Redis perso éventuellement déjà lancé.

### Commandes raccourcies

```bash
pnpm dev:up      # Démarrage en background
pnpm dev:logs    # Suivre les logs
pnpm dev:down    # Arrêt (volumes conservés)
pnpm dev:reset   # Arrêt + suppression des volumes (reset DB / MinIO complet)
```

### Vérifier que ça tourne

```bash
docker compose -f docker-compose.dev.yml ps
```

Tous les services doivent être `healthy` (sauf `minio-bootstrap` qui sort après avoir créé le bucket — c'est normal).

## 2. API (apps/api)

```bash
cd apps/api
cp .env.example .env       # Si pas déjà fait
pnpm dev:api               # Depuis la racine, ou : pnpm -F api dev
```

**Première fois** :

```bash
pnpm -F api exec node ace migration:run
pnpm -F api exec node ace db:seed
```

L'API écoute sur http://localhost:3333.

### Bascule SQLite (mode dégradé)

Si Docker n'est pas dispo, on peut basculer sur SQLite :

```bash
# Dans apps/api/.env
DB_CONNECTION=sqlite
```

Les migrations tournent sur les deux. Pour les jobs/storage/mail, il faut quand même Redis/MinIO/Mailhog — donc Docker reste recommandé.

## 3. Web (apps/web)

```bash
pnpm dev:web
# → http://localhost:5173
```

Tant que `VITE_USE_MOCKS=true` dans `apps/web/.env`, le SPA tape MSW et n'a pas besoin de l'API. Quand le backend est prêt à servir un domaine, on bascule la valeur sur `false`.

## 4. Trousseau de variables d'env

Voir `apps/api/.env.example` — c'est la source de vérité. Récap :

- **PG_*** : connexion Postgres (default ports décalés docker-compose)
- **REDIS_*** : BullMQ
- **S3_*** : MinIO (driver S3 d'@adonisjs/drive)
- **MAIL_*** + **SMTP_*** : Mailhog en dev, Resend en prod (`MAIL_DRIVER=resend` + `RESEND_API_KEY`)
- **OCR_PROVIDER** : `mock` en dev, `mistral` quand l'API key est en place
- **ACCESS_TOKEN_TTL_MINUTES** / **REFRESH_TOKEN_TTL_DAYS** : durées d'auth

## 5. Tester les routes — collection Bruno

Une collection [Bruno](https://www.usebruno.com/) prête à l'emploi est dans `/bruno/`. Elle couvre toutes les routes documentées et capture le token + les IDs créés au fil des requêtes.

```bash
# Open Collection → sélectionne le dossier bruno/
# Puis sélectionne l'environnement "local" en haut à droite
```

Parcours recommandé : Signup → Get profile → Update org → Create client → List plans → Create invoice → Get detail → Mark paid → Get org (vérifier rubisCount). Détails dans `/bruno/README.md`.

## 6. Données de seed

`pnpm -F api exec node ace db:seed` lance :

- `default_plans_seeder` — 4 plans pré-fournis (Standard B2B, Rapide, Patient, Ferme)
- `demo_data_seeder` — compte `demo@rubis.fr` + clients + factures (dev uniquement)

Les seeders réutilisent les fixtures de `apps/web/src/mocks/seed.ts` pour garantir la cohérence MSW ↔ vraie API.