Agents commerciaux

Vue d'ensemble

Les agents commerciaux (role: agentCommercial) prospectent des vendeurs et acheteurs, suivent leur activité quotidienne et perçoivent des commissions. Ils utilisent principalement :

Tranoo Pro (agents type Tranoo_pro) — démos vendeurs, KPIs campagnes/abonnements
Tranoo (agents type Tranoo) — prospection acheteurs
Dashboard web — création de comptes agent, suivi admin, retraits

Types d'agents

Le champ User.typeAgent distingue deux profils :

Type	Cible	Dashboard API
`Tranoo_pro`	Vendeurs Tranoo Pro	`/api/agents/me-pro/*`
`Tranoo`	Acheteurs Tranoo	`/api/agents/me-tranoo/*`

Les routes génériques /api/agents/me/* restent disponibles ; les routes me-pro et me-tranoo vérifient le typeAgent.

Architecture

┌─────────────────┐     parrainage      ┌──────────────┐
│  Agent          │ ──────────────────► │  Vendeurs /  │
│  (Tranoo Pro)   │   referralCode      │  Acheteurs   │
└────────┬────────┘                     └──────┬───────┘
         │                                     │
         │  KPIs, présence GPS                 │  actions métier
         ▼                                     ▼
┌─────────────────┐     demo events     ┌──────────────┐
│  Dashboard      │ ◄────────────────── │  Tranoo Pro  │
│  agent / admin  │   POST /track       │  (mobile)    │
└─────────────────┘                     └──────────────┘

Modèles de données

Modèle	Rôle
`AgentDailyLog.js`	Journal quotidien (zone, GPS, prospects, observation admin)
`AgentEarning.js`	Gains, commissions, retraits
`DemoEvent.js`	Événements de démonstration mobile
`Referral.js`	Lien agent → filleul (voir Parrainage)

Types de gains (`AgentEarning.type`)

Type	Description
`referral_signup`	Bonus à l'inscription d'un filleul
`commission_subscription`	Commission sur abonnement vendeur filleul
`commission_publicite`	Commission sur campagne pub filleul
`daily_presence`	Prime de présence journalière (GPS)
`withdrawal`	Retrait enregistré par l'admin (montant négatif)

Endpoints API — Agent (mobile / web)

Préfixe : /api/agents — auth + rôle agentCommercial

Méthode	Route	Description
`GET`	`/me/dashboard`	Tableau de bord (query `?date=YYYY-MM-DD`)
`GET`	`/me-pro/dashboard`	Idem, réservé `typeAgent: Tranoo_pro`
`GET`	`/me-tranoo/dashboard`	Idem, réservé `typeAgent: Tranoo`
`POST`	`/me/daily`	Enregistre zone + localisation GPS du jour
`POST`	`/me/daily/prospects/increment`	Incrémente le compteur de prospects
`GET`	`/leaderboard`	Classement agents
`GET`	`/me-pro/leaderboard`	Classement agents Pro
`GET`	`/me-tranoo/leaderboard`	Classement agents Tranoo

Réponse dashboard (extrait)

{
  "agent": { "id": "...", "typeAgent": "Tranoo_pro", "referralCode": "A1B2C3D4" },
  "stats": {
    "totalReferrals": 12,
    "completedReferrals": 12,
    "totalEarnings": 45000,
    "currentBalance": 32000
  },
  "daily": {
    "dateKey": "2026-09-01",
    "prospectsApproached": 8,
    "demonstrations": 5,
    "boutiquesCreees": 2,
    "abonnementsVendus": 1,
    "campagnesLancees": 3,
    "revenueAbonnement": 5000,
    "revenueCampagne": 2000,
    "dailyBonusCredited": true,
    "dailyPresenceBonusXof": 2000
  }
}

KPIs journaliers

Calculés par computeKpisForRangeV2 dans agentController.js :

KPI	Source
`demonstrations`	Événements `DemoEvent` (voir ci-dessous)
`boutiquesCreees`	Vendeurs filleuls inscrits sur la période
`abonnementsVendus`	Paiements `subscription` réussis des filleuls
`campagnesLancees`	Paiements publicité réussis des filleuls
`campagnesDemandees`	Demandes `Publicite` créées (payées ou non)
`revenueAbonnement`	Commissions `commission_subscription` créditées
`revenueCampagne`	Commissions `commission_publicite` créditées

Objectifs métier (retournés dans `daily.objectifs`)

Objectif	Valeur
Prospects / jour	20
Abonnements min. avant retrait	4
Campagnes min. avant retrait	4

Tracking des démonstrations

Endpoint

POST /api/demo-events/track — auth vendeur ou acheteur

Événements trackés (mobile Tranoo Pro)

`eventType`	Écran / action
`seller_create_started`	Bouton Aperçu (`create_sell.dart`, `create_sell2.dart`)
`seller_create_completed`	Fin de création article
`subscription_initiated`	Souscrire maintenant (`subscription_payment.dart`)
`campaign_initiated`	Boostez vos ventes (`cars_info.dart`)
`listing_opened_une`	Ouverture page À la une
`notification_clicked`	Clic notification
`alert_created`	Création alerte

Règle de comptage (`demonstrations`)

Compte les événements commerciaux listés ci-dessus sur la période
Cooldown : au plus 1 démo toutes les DEMO_COOLDOWN_MINUTES (défaut 15 min)
Résolution de l'agent : via Referral.referrerId ou compte lié sur la fiche agent

Anti-spam

Variable	Défaut	Effet
`DEMO_EVENT_DEDUP_MS`	`30000`	Ignore les doublons même `eventType` + `sessionKey` en 30 s
`DEMO_COOLDOWN_MINUTES`	`15`	Intervalle minimum entre deux démos comptées

La sessionKey est dérivée du token Firebase (uid:auth_time) — un simple refresh de token ne crée pas une nouvelle démo.

Guide détaillé : tranoo-api/docs/DEMO_TRACKING_TRANOO_PRO.md

Prime de présence journalière

Lorsqu'un agent enregistre sa localisation GPS (zoneLocation.lat/lng) via POST /me/daily :

Le backend crédite une fois par jour la prime daily_presence
Montant par défaut : 2000 XOF (AGENT_DAILY_PRESENCE_BONUS_XOF)
Stocké dans AgentEarning avec type: daily_presence

Configuration : src/config/agentConfig.js

Endpoints API — Admin

Méthode	Route	Rôles	Description
`POST`	`/api/agents`	superAdmin, principal, gestionnaire, admin	Crée un agent
`GET`	`/api/agents/admin/consolidated`	Admin	Stats consolidées tous agents
`GET`	`/api/agents/:id/referral-stats`	Admin	Stats parrainage d'un agent
`GET`	`/api/agents/:id/referrals`	Admin	Liste filleuls
`GET`	`/api/agents/:id/pro-monitor`	Admin	Suivi journalier Pro
`POST`	`/api/agents/:id/withdrawals`	Admin	Enregistre un retrait
`GET`	`/api/agents/withdrawals`	Admin dashboard	Liste tous les retraits
`POST`	`/api/agents/admin/backfill-daily-presence`	Admin	Rattrapage primes présence
`POST`	`/api/agents/:id/daily/observation`	Admin	Ajoute une observation sur le journal

Inscription web

Page publique : https://tranoo.store/inscription-agent-com

Variables d'environnement

Variable	Défaut	Description
`AGENT_DAILY_PRESENCE_BONUS_XOF`	`2000`	Prime présence GPS
`DEMO_COOLDOWN_MINUTES`	`15`	Cooldown entre démos comptées
`DEMO_EVENT_DEDUP_MS`	`30000`	Déduplication événements

Fichiers source

Fichier	Rôle
`src/controllers/agentController.js`	Dashboard, KPIs, retraits
`src/controllers/demoEventController.js`	Tracking démos
`src/routes/agent.js`	Routes agents
`src/routes/demoEvent.js`	Route `/track`
`src/config/agentConfig.js`	Configuration primes

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

Voir aussi

Parrainage — codes et filleuls
Vue d'ensemble
Base de données — AgentDailyLog, DemoEvent
Déploiement — URL inscription agent

Vue d'ensemble​

Types d'agents​

Architecture​

Modèles de données​

Types de gains (AgentEarning.type)​

Endpoints API — Agent (mobile / web)​

Réponse dashboard (extrait)​

KPIs journaliers​

Objectifs métier (retournés dans daily.objectifs)​

Tracking des démonstrations​

Endpoint​

Événements trackés (mobile Tranoo Pro)​

Règle de comptage (demonstrations)​

Anti-spam​

Prime de présence journalière​

Endpoints API — Admin​

Inscription web​

Variables d'environnement​

Fichiers source​

Voir aussi​