ordinarthur 27cfa9ac13 docs(bruno): collection complète des routes API + environnement local

Collection Bruno (.bru text files, comme Postman mais file-based versionable) qui couvre l'API V1 actuelle. Open Collection → bruno/ → sélectionner l'environnement "local".

Domaines couverts (22 requêtes) :
- 00-Auth : Signup, Login, Logout
- 01-Account : Get/Update profile
- 02-Organizations : Get/Update my org
- 03-Clients : List, List+stats, Search, Create, Create duplicate (409), Create without email (422), Get detail, Update
- 04-Plans : List, Get by slug, Update (steps remplacés)
- 05-Invoices : List, List+filters, Counts, Create, Get detail, Mark paid

Environnement local (bruno/environments/local.bru) :
- baseUrl, email/password/fullName en dur
- token, userId, organizationId, clientId, invoiceId remplis automatiquement par les script:post-response

Chaque requête a :
- assertions Chai (statut, shape de la réponse)
- bloc docs avec sémantique métier + erreurs typiques
- inheritance auth Bearer via folder.bru pour ne pas répéter le header

Mise à jour de docs/tech/dev-setup.md pour pointer vers la collection.

Le parcours recommandé Signup → Update org → Create client → Create invoice → Mark paid couvre le happy path et permet de checker rubisCount qui s'incrémente.

2026-05-06 14:40:55 +02:00

3.8 KiB

Raw Blame History

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

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

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)

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 :

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 :

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

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 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.

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

3.8 KiB Raw Blame History