9eaac0c7ef
Audit cross-doc/code, batch tech : architecture, backend, frontend, dev-setup. Corrige les claims qui pouvaient induire un dev en erreur (noms de services K3s, hostnames Traefik, Tuyau, queue wrapper, seeders, env vars, polices). architecture.md - Composants : status « À écrire » → « ✅ Déployé » (apps/web, apps/api, packages/shared) ; ajout Redis Deployment K3s ; OCR = Mistral choisi ; mail = Resend (sortant) + OVH MX (entrant) validés - §7.5 Pods K3s : noms réels (rubis-api / rubis-web / rubis-landing / rubis-redis, pas de *-svc) ; pas d'IngressRoute api.rubis.pro (l'API est servie via app.rubis.pro/api/* proxifié par nginx du pod web) ; PG/MinIO en URL directe dans la ConfigMap, pas de Service ExternalName - §10 Décisions en attente : ADRs 019-024 mises à jour (tranchées / obsolètes), suppression du wording « à venir » pour les choix déjà figés dans le code backend.md - Note de cohérence en tête : pointe vers start/routes.ts comme source de vérité de la surface API (~80 routes — Stripe, Demo, AI, Microsoft SSO, admin blog, posts publics, KPIs timeseries) que cette doc n'inventorie pas exhaustivement - §1 Vue d'ensemble : Tuyau marqué « non utilisé en pratique » (présent en deps mais zéro import côté SPA), partage de types via packages/shared. OCR Mistral choisi. Mail Resend choisi. BullMQ direct (workers inline pod API). Sentry ADR-024. - §2 Stack : queue = BullMQ direct (pas @rlanz/bull-queue, qui n'est pas installé) ; type-sharing = packages/shared - §2 Dépendances : remplacé la todo-list pré-livraison par la liste réelle des packages dans apps/api/package.json - §3 Repo layout : `database/factories/` (dossier) → `factories.ts` (mono-fichier) ; `database/seeders/{default_plans,demo_data}` → inexistants, services à la place - §13.2 Jobs : ProcessOcrJob + RecomputeKpisJob retirés (n'existent pas — OCR synchrone via services/import_batch.ts, KPIs calculés on-the-fly). Liste des jobs réels : send_relance, send_checkin, send_payment_thanks - env vars : MINIO_* → S3_* (cf. .env.example + manifest k3s) ; bucket prod = rubis-prod-invoices frontend.md - Note de cohérence en tête : Tuyau pas utilisé, tokens dans packages/ui (pas inline), polices @fontsource-variable (pas Google Fonts via <link>) - §1 Vue d'ensemble : client API = fetch minimaliste dans apps/web/src/lib/api.ts ; périmètre livré = ~15 routes _app/ - §3 Polices : section Google Fonts → @fontsource-variable (avec note preload woff2 critique sur la landing Astro) - §4 Routes : arbo `_onboarding/` (faux) → `onboarding/` (réel, segment URL) + ajout admin.blog*, clients_.$id, insights, parametres_.abonnement, plans_.nouveau, factures_.import - §6 Tuyau : section marquée « historique, non utilisé en V1 » avec note explicative en tête - §10 env vars : VITE_API_URL=https://api.rubis.pro → vide (proxifié same-origin par nginx) + ajout VITE_USE_MOCKS, VITE_SENTRY_DSN_WEB, VITE_APP_VERSION dev-setup.md - Mailhog → Mailpit (3 occurrences) — c'est ce qui tourne dans docker-compose.dev.yml Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
112 lines
3.8 KiB
Markdown
112 lines
3.8 KiB
Markdown
# 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, Mailpit) + 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/Mailpit — 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_*** : Mailpit 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.
|