ordinarthur 9eaac0c7ef docs(audit-2/3): aligner doc tech sur le code livré

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>

2026-05-09 19:13:44 +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, 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

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/Mailpit — 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_* : 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 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