Vue d'ensemble

Comment Qovans est construit, pourquoi ces choix techniques, et comment les pieces s'assemblent.

Qovans est une plateforme e-commerce B2B qui permet a vos clients de commander des produits industriels (profiles aluminium, huisseries, accessoires) en ligne. Elle se connecte en temps reel a votre ERP Cegid pour les stocks, les prix et les commandes.

Comment ca marche

Le systeme a trois composants principaux :

Le frontend (ce que vos clients voient) — une application web Next.js qui tourne sur le port 3000
Le backend (la logique metier) — une API FastAPI qui tourne sur le port 8000
Cegid (votre ERP) — accessible uniquement via le VPN Audaxium

Quand un client se connecte et consulte le catalogue, voici ce qui se passe :

Navigateur client
    │
    ▼
Frontend (Next.js, port 3000)
    │
    ▼
Backend API (FastAPI, port 8000)
    │
    ├──► PostgreSQL (port 5432)    ← utilisateurs, paniers, config
    ├──► Cegid API (192.168.4.110) ← stocks, prix, commandes
    └──► MinIO S3 (port 9000)      ← images produits, PDF

Pourquoi deux bases de donnees ?

Cegid est la source de verite pour tout ce qui est commercial (produits, prix, stocks, commandes). Mais l'API Cegid est lente et limitee a 50 resultats par requete — impossible d'afficher un catalogue performant en temps reel.

La solution : PostgreSQL stocke un cache local des produits et prix, synchronise regulierement. Les stocks et les commandes, eux, sont toujours lus en temps reel depuis Cegid.

Donnee	Stockee ou ?	Pourquoi
Utilisateurs, auth, roles	PostgreSQL	Pas de gestion utilisateurs dans Cegid
Paniers	PostgreSQL	Un panier par depot, avec articles lies
Produits et prix	PostgreSQL (cache)	Performance catalogue, sync periodique
Stocks par depot	Cegid (temps reel)	Toujours a jour
Commandes, devis, factures	Cegid (temps reel)	Source de verite ERP
Images produits	MinIO S3	Stockage fichiers independant
Regles de transport	PostgreSQL	Configuration specifique au site

Stack technique

Composant	Technologie	Pourquoi ce choix
Backend	FastAPI (Python 3.11)	Async natif, ideal pour les appels Cegid concurrents
Frontend	Next.js 15 + React 19	SSR, routing moderne, TypeScript strict
Base de donnees	PostgreSQL 15	Fiable, performant, migrations Alembic
UI	shadcn/ui + Tailwind CSS v4	Composants modernes, personnalisables
Stockage	MinIO (compatible S3)	Auto-heberge, pas de dependance cloud
Reverse proxy	Caddy	HTTPS automatique via Let's Encrypt
Deploiement	Docker Compose	Un seul fichier pour tout demarrer

Structure des fichiers

Voici les fichiers importants a connaitre :

Backend (`backend/`)

Dossier	Contenu
`app/main.py`	Point d'entree — CORS, rate limiting, health check, proxy images
`app/config.py`	Toutes les variables d'environnement (~50 parametres)
`app/api/v1/`	Endpoints REST (auth, produits, panier, commandes, admin)
`app/models/`	26 modeles SQLAlchemy (tables PostgreSQL)
`app/services/`	Logique metier (19 services dont `cegid_client.py`)
`app/schemas/`	Validation Pydantic (ce qui entre et sort de l'API)
`alembic/versions/`	66 migrations de base de donnees
`scripts/`	Scripts de sync et import (produits, stocks, familles)

Frontend (`frontend/src/`)

Dossier	Contenu
`app/(auth)/`	Pages connexion, mot de passe oublie
`app/(main)/`	Pages client (catalogue, panier, commandes, devis, factures)
`app/(admin)/admin/`	Pages administration (30+ pages)
`components/`	Composants React reutilisables
`lib/api/`	13 clients HTTP (un par domaine fonctionnel)
`lib/hooks/`	16 hooks React Query (gestion du cache serveur)
`lib/stores/`	6 stores Zustand (etat client local)
`messages/`	Traductions fr/en

Concepts cles

Authentification — JWT avec access token (15 min) + refresh token (1 jour). Support 2FA par email ou TOTP. Les roles sont customer, admin et sales.

Panier par depot — chaque client a un panier par depot selectionne. Changer de depot cree un nouveau panier vide (l'ancien est conserve).

Franco de port — au-dessus d'un seuil (5 500 EUR HT par defaut), la livraison est gratuite. Certains clients VIP ont un seuil reduit (ex: 4 400 EUR).

Articles lies — certains produits declenchent automatiquement l'ajout d'accessoires (obligatoires ou optionnels) dans le panier.

Produits configurables — les profiles aluminium ont des variantes par couleur et longueur. Le code produit encode ces informations (ex: C12008129 = Blanc, Lisse 81, 2940mm).