Parrainage

Vue d'ensemble

Le système de parrainage lie un parrain (agent commercial ou utilisateur avec referralCode) à un filleul inscrit via ce code. Il alimente les statistiques agents, le tracking des démos et les commissions.

Modèles de données

Referral.js

Champ	Description
referrerId	Utilisateur parrain (souvent agentCommercial)
referredId	Utilisateur filleul
referralCode	Code utilisé à l'inscription
status	pending ou completed
rewardAmount	Montant de récompense enregistré
completedAt	Date de finalisation

:::info Comportement actuel À la création, le statut est directement completed dès que le filleul est enregistré (le lien est actif pour stats et commissions). :::

ReferralTariff.js

Tarifs personnalisés assignables par agent (User.assignedReferralTariff).

Champ	Description
amount	Montant récompense
isActive	Tarif actif ou non

ReferralSettings.js

Configuration globale (singleton) :

Champ	Description
rewardAmount	Montant par défaut si pas de tarif assigné
actif	Parrainage activé ou non

Flux d'inscription avec code

1. Le parrain partage son referralCode (champ User.referralCode)
2. Le filleul saisit le code à l'inscription (mobile ou web)
3. POST /api/referrals/create crée le document Referral
4. Si le parrain est un agent : crédit AgentEarning type referral_signup
5. Les actions du filleul sont rattachées à l'agent pour les KPIs et démos

Contraintes

• Un filleul ne peut être parrainé qu'une seule fois
• Auto-parrainage interdit
• Code invalide → erreur 400

Endpoints API

Préfixe : /api/referrals

Utilisateur connecté

Méthode	Route	Description
GET	/stats	Statistiques de parrainage de l'utilisateur
GET	/my-referrals	Liste des filleuls
GET	/monthly-stats	Stats mensuelles (?month=YYYY-MM)
POST	/create	Crée un parrainage (code + utilisateur courant)
PUT	/complete/:referralId	Finalise un parrainage en attente

Admin

Méthode	Route	Description
GET	/all	Tous les parrainages
GET	/settings	Configuration globale
PUT	/settings	Met à jour la configuration

Rôles admin requis : admin, superAdmin, principal, moderateur, gestionnaire.

Tarifs parrainage (admin)

Préfixe : /api/referral-tariffs

Gestion des grilles tarifaires assignables aux agents via User.assignedReferralTariff.

Lien avec les agents commerciaux

Mécanisme	Description
Filleuls vendeurs	Source des KPIs abonnementsVendus, campagnesLancees
Résolution démo	DemoEvent.agent dérivé de Referral.referrerId
Commissions	commission_subscription, commission_publicite sur paiements filleuls
Dashboard admin	/api/agents/:id/referral-stats, /api/agents/:id/referrals

Voir Agents commerciaux.

Génération des codes

Les codes sont générés automatiquement :

crypto.randomBytes(4).toString('hex').toUpperCase();
// Exemple : A1B2C3D4

Stockés sur User.referralCode (unique par utilisateur éligible).

Fichiers source

Fichier	Rôle
src/controllers/referralController.js	CRUD parrainages
src/routes/referral.js	Routes /api/referrals
src/routes/referralTariff.js	Tarifs admin
src/models/Referral.js	Schéma parrainage
src/models/ReferralTariff.js	Schéma tarifs
src/models/ReferralSettings.js	Configuration globale

OpenAPI : paths/09-tricycles-referrals-agents.js. Voir API Swagger.

Voir aussi

• Agents commerciaux
• Base de données — modèles Referral
• Vue d'ensemble