#56 — Onboarding Revendeur

IMPLÉMENTÉ

Priorité: 🔴 CRITIQUE · Type: TYPE B + D · Conteneur: rgz-api + rgz-web · Code: app/api/v1/endpoints/onboarding.py + dashboard/src/pages/OnboardingManager.jsxDépendances: #1 rgz-api, #31 vlan-allocation, #33 cpe-preconfig

Guide Revendeur Disponible

Consultez le Guide Revendeur complet et le Parcours Revendeur J0→J12 pour une vision narrative.

Description

Le système d'onboarding automatise la conversion des revendeurs candidats en partenaires actifs ACCESS sur 8 étapes, du jour J0 (candidature) au jour J12+ (transition opérationnelle). L'interface admin propose un pipeline visuel complet avec des panneaux détaillés par étape : formulaire RF, signature contrat, configuration VLAN/CPE (avec placeholder FortiGate), checklist installation terrain, formation revendeur, go-live avec test RADIUS, et suivi post-lancement.

Chaque étape dispose d'un composant React dédié avec formulaires, checklists interactives, StatCards, et actions spécifiques. Le backend expose 3 endpoints stub (mock) pour alimenter l'UI immédiatement, en attendant l'intégration DB complète.

Architecture UI

Layout principal

┌─────────────────────────────────────────────┐
│ PageHeader "Pipeline Onboarding Revendeurs" │
├─────────────────────────────────────────────┤
│ StepMetrics (8 cartes compteurs cliquables) │
├──────────────────┬──────────────────────────┤
│ Liste candidats  │ Panneau détail étape     │
│ (table + tabs    │ ┌──────────────────────┐ │
│  + filtres       │ │ Info candidat        │ │
│  + recherche)    │ ├──────────────────────┤ │
│                  │ │ OnboardingPipeline   │ │
│  Barre progress  │ ├──────────────────────┤ │
│  par revendeur   │ │ StepXxx.jsx          │ │
│                  │ │ (contenu spécifique) │ │
│                  │ ├──────────────────────┤ │
│                  │ │ Notes + SMS toggle   │ │
│                  │ └──────────────────────┘ │
└──────────────────┴──────────────────────────┘

Pipeline 8 étapes

Transition d'état : 0 → 1 → 2 → 3 → 4 → 5 → 6 → 7

ÉTAPE 0 — CANDIDATURE        (StepCandidature.jsx)
ÉTAPE 1 — VALIDATION RF      (StepRFValidation.jsx)
ÉTAPE 2 — CONTRAT            (StepContrat.jsx)
ÉTAPE 3 — VLAN / CPE         (StepVlanCpe.jsx)
ÉTAPE 4 — INSTALLATION       (StepInstallation.jsx)
ÉTAPE 5 — FORMATION          (StepFormation.jsx)
ÉTAPE 6 — GO-LIVE            (StepGoLive.jsx)
ÉTAPE 7 — TRANSITION         (StepTransition.jsx)

Composants React (12 fichiers)

Composant	Fichier	Lignes	Rôle
OnboardingManager	`pages/OnboardingManager.jsx`	383	Page principale, layout 2 colonnes
OnboardingPipeline	`components/onboarding/OnboardingPipeline.jsx`	102	Barre horizontale 8 nœuds (desktop) + liste verticale (mobile)
StepMetrics	`components/onboarding/StepMetrics.jsx`	93	Grille 8 cartes compteurs par étape
StepCandidature	`components/onboarding/StepCandidature.jsx`	125	Infos candidat + GPS + Google Maps
StepRFValidation	`components/onboarding/StepRFValidation.jsx`	280	Formulaire RF + StatCards SNR/distance
StepContrat	`components/onboarding/StepContrat.jsx`	214	IFU + signature + paiement OTP
StepVlanCpe	`components/onboarding/StepVlanCpe.jsx`	197	Config VLAN + FortiGate placeholder + CPE table
StepInstallation	`components/onboarding/StepInstallation.jsx`	177	Checklist 6 items + iperf3 DL/UL
StepFormation	`components/onboarding/StepFormation.jsx`	180	Checklist formation + planning
StepGoLive	`components/onboarding/StepGoLive.jsx`	150	Récap 6 étapes + test RADIUS
StepTransition	`components/onboarding/StepTransition.jsx`	163	KPI J+1 + checklist suivi

Total : ~2064 lignes de code frontend

Détail par étape

Étape 0 — Candidature (`StepCandidature.jsx`)

Affiche les informations soumises par le revendeur candidat.

Données affichées :

Référence candidature : CAND-YYYYMM-XXXX
Entreprise (company_name), responsable (owner_first_name + owner_last_name)
Téléphone, IFU (13 chars, mono), ville, quartier
Localisation GPS avec lien Google Maps (si lat/lng disponibles)
Soumis par (admin), date soumission

Action : "Envoyer en validation RF →" (onAction('complete', {}))

Étape 1 — Validation RF (`StepRFValidation.jsx`)

Formulaire complet de validation radio-fréquence par le technicien terrain.

Mode édition (pending/in_progress) :

Champ	Type	Valeurs
Distance (km)	number	min=0, step=0.1
SNR estimé (dB)	number	min=0, max=100, step=0.1
Obstacles	text	"Bâtiments, arbres, terrain..."
Fréquence (GHz)	select	2.4, 5.2, 5.4, 5.8
Classification	select	V1 (LOS <3km), V2 (NLOS 3-8km), V3 (NLOS >8km)
Technicien RF	text	Nom du technicien assigné
Notes RF	textarea	Observations supplémentaires

StatCards temps réel :

SNR : vert (≥25 dB), orange (15-24 dB), rouge (<15 dB)
Distance : vert (≤3 km), orange (3-8 km), rouge (>8 km)

Actions : "Approuver RF" (complete) / "Rejeter" (fail)

Mode lecture seule (completed) : Toutes les valeurs en lecture + date validation

Étape 2 — Contrat (`StepContrat.jsx`)

Validation IFU, signature contrat, et paiement onboarding.

Sections :

IFU : Numéro mono + badge "Vérifié" / "En attente"
Contrat : Statut signature (signé + date ou en attente)
Paiement onboarding :
- Montant : 50 000 FCFA (fixe, disabled)
- Provider : select MTN_MOMO, MOOV_FLOOZ, CELTIIS_CASH, WAVE_BENIN
- Code OTP : input 6 chiffres (tracking-widest, mono)
- Transaction ID : affiché après validation

Actions : "Envoyer OTP signature" + "Confirmer contrat signé" (actif si OTP 6 chars)

Étape 3 — VLAN / CPE (`StepVlanCpe.jsx`)

Configuration réseau avec placeholder FortiGate.

Affichage 4 champs lecture seule :

Champ	Source	Fallback
VLAN ID	`reseller.vlan_id` ou `stepData.data.vlan_id`	"—"
Subnet	`stepData.data.subnet`	"—"
NAS-ID	`reseller.nas_id` ou `stepData.data.nas_id`	"—"
SSID	`stepData.data.ssid`	"—"

Boutons :

"🔄 Synchroniser depuis FortiGate" → DÉSACTIVÉ (tooltip: "Intégration en cours de développement")
"Saisie manuelle" → Modal avec 4 champs (VLAN ID, Subnet, NAS-ID, SSID)

Section CPE : Table 2 lignes (CPE 1, CPE 2) : Serial, MAC, IP, Statut

Action : "Confirmer VLAN + CPE prêts" (complete)

Étape 4 — Installation terrain (`StepInstallation.jsx`)

Checklist interactive terrain avec résultats iperf3.

Checklist 6 items (cases à cocher) :

[ ] CPE 1 installé et alimenté
[ ] CPE 2 installé et alimenté
[ ] Alignement antenne vérifié
[ ] Test iperf3 DL > 5 Mbps
[ ] Test iperf3 UL > 1 Mbps
[ ] Photo installation prise

Barre de progression : N/6 items cochés, couleur verte à 100%

Résultats iperf3 :

Download (Mbps) : input + StatCard (vert si ≥5, rouge sinon)
Upload (Mbps) : input + StatCard (vert si ≥1, rouge sinon)

Champs : Technicien terrain + Notes

Action : "Valider installation" (actif seulement si 6/6 cochés)

Étape 5 — Formation (`StepFormation.jsx`)

Checklist formation revendeur + planification.

Checklist 6 items :

[ ] Connexion portail captif
[ ] Gestion abonnés
[ ] Facturation et split 50/50
[ ] Génération de vouchers
[ ] Dashboard revendeur
[ ] Procédure support / RMA

Planification :

Date formation : date picker
Nom du formateur : text
Durée : badge "2h" (indicatif)

Ressources : Guide PDF + Tutoriel vidéo (placeholder "Disponible prochainement")

Action : "Confirmer formation terminée" (actif si 6/6 cochés)

Étape 6 — Go-Live (`StepGoLive.jsx`)

Récapitulatif complet + test RADIUS avant activation.

Récap 6 étapes précédentes (lecture seule) :

Étape	Vérifié via
Candidature validée	`allStepsData.candidature.status === 'completed'`
RF approuvé	`allStepsData.rf_validation.status === 'completed'`
Contrat signé	`allStepsData.contract.status === 'completed'`
VLAN alloué	`allStepsData.vlan_cpe.status === 'completed'`
Installation terminée	`allStepsData.installation.status === 'completed'`
Formation complétée	`allStepsData.training.status === 'completed'`

Alertes : Bannière orange si étapes incomplètes

Badge classification : Affiché depuis allStepsData.rf_validation.data.classification

Test RADIUS : Section dédiée avec note FortiGate NAS-Identifier

Action : "Activer revendeur → Go-Live" (désactivé si étapes incomplètes)

Étape 7 — Transition (`StepTransition.jsx`)

Suivi post go-live J+1.

Badge : "J+1 post go-live"

Métriques temps réel (3 KPICards) :

Sessions actives (bleu)
Abonnés inscrits (vert)
Revenus J0 en FCFA (jaune)

Incidents : Liste ou "Aucun incident signalé"

Checklist suivi :

[ ] Première transaction KKiaPay vérifiée
[ ] Revendeur autonome confirmé
[ ] Support 24h sans incident

Action : "Clôturer onboarding" (complete)

Endpoints API (Backend Stubs)

GET `/api/v1/resellers/{reseller_id}/onboarding/details`

Retourne les données enrichies du panneau d'onboarding.

json

{
  "reseller_id": "uuid",
  "reference": "CAND-202602-0042",
  "current_step": 3,
  "step_status": "in_progress",
  "steps": {
    "candidature": {
      "status": "completed",
      "completed_at": "2026-02-10T09:00:00Z",
      "data": { "ifu": "3201234567890", "gps": [6.37, 2.39], "submitted_by": "Admin NOC" }
    },
    "rf_validation": {
      "status": "completed",
      "completed_at": "2026-02-11T14:30:00Z",
      "data": {
        "classification": "V1",
        "distance_km": 1.2,
        "snr_db": 32,
        "obstacles": "Aucun",
        "frequency_ghz": 5.8,
        "technician": "Ing. Dossou",
        "notes": "Ligne de vue directe"
      }
    },
    "contract": {
      "status": "completed",
      "completed_at": "2026-02-12T10:00:00Z",
      "data": {
        "ifu_verified": true,
        "signed_at": "2026-02-12T09:45:00Z",
        "payment_status": "completed",
        "payment_amount_fcfa": 50000,
        "payment_provider": "MTN_MOMO",
        "transaction_id": "TXN-20260212-001"
      }
    },
    "vlan_cpe": { "status": "in_progress", "data": { "vlan_id": null, "subnet": null, "nas_id": null, "ssid": null, "cpe_list": [] } },
    "installation": { "status": "pending", "data": {} },
    "training": { "status": "pending", "data": {} },
    "go_live": { "status": "pending", "data": {} },
    "transition": { "status": "pending", "data": {} }
  }
}

PUT `/api/v1/resellers/{reseller_id}/onboarding/step`

Met à jour une étape d'onboarding.

json

// Request
{
  "step": "rf_validation",
  "action": "complete",
  "data": {
    "classification": "V1",
    "distance_km": 1.2,
    "snr_db": 32,
    "technician": "Ing. Dossou"
  },
  "notify_reseller": true
}

// Response 200
{
  "success": true,
  "step": "rf_validation",
  "action": "complete",
  "message": "Étape mise à jour"
}

GET `/api/v1/onboarding/stats`

Statistiques globales pipeline (pour StepMetrics).

json

{
  "by_step": {
    "candidature": 12,
    "rf_validation": 8,
    "contract": 5,
    "vlan_cpe": 3,
    "installation": 2,
    "training": 4,
    "go_live": 1,
    "transition": 15
  },
  "total_active": 50,
  "avg_days_to_golive": 11.3
}

Enums (valeurs exactes)

python

OnboardingStepKey  = candidature | rf_validation | contract | vlan_cpe | installation | training | go_live | transition
StepStatus         = pending | in_progress | completed | failed
StepAction         = complete | fail | save_draft
ResellerClassif    = V1 | V2 | V3
PaymentProvider    = MTN_MOMO | MOOV_FLOOZ | CELTIIS_CASH | WAVE_BENIN

Configuration

env

# .env.example
ONBOARDING_STEP_TIMEOUT_DAYS=3          # Relance si étape pas validée
ONBOARDING_IPERF_MIN_DL_MBPS=5         # Seuil iperf3 download
ONBOARDING_IPERF_MIN_UL_MBPS=1         # Seuil iperf3 upload
ONBOARDING_SNR_GOOD_THRESHOLD=25       # SNR vert (dB)
ONBOARDING_SNR_WARNING_THRESHOLD=15    # SNR orange (dB)
ONBOARDING_PAYMENT_AMOUNT_FCFA=50000   # Montant onboarding fixe

Intégration FortiGate (Placeholder)

Le bouton "Synchroniser depuis FortiGate" dans StepVlanCpe est intentionnellement désactivé. L'intégration FortiGate/Cisco est prévue pour une phase ultérieure :

Étape 3 : allocation VLAN automatique depuis FortiGate API
Sync NAS-ID, subnet, SSID depuis le firewall
Configuration CPE via SSH batch (#33)

En attendant, la "Saisie manuelle" permet de renseigner les 4 champs VLAN manuellement.

Intégration Avec Autres Outils

#1 rgz-api: Hub central, tous endpoints onboarding
#31 vlan-allocation: Appelé à étape 3 (saisie manuelle ou futur FortiGate)
#33 cpe-preconfig: Configuration CPE à étape 3-4
#79 iperf3-test: Résultats à étape 4 (DL/UL Mbps)
#11 ocr-inscription: Validation documents (futur étape 0)
#61 sms-template: Notifications chaque transition (checkbox SMS)
#63 email-notification: Notifications email
#51 dashboard-reseller: Affiche onboarding_step en temps réel
#19 moteur-facturation: Déclenché après go-live

Implémentation

Fait

[x] Page OnboardingManager avec layout 2 colonnes
[x] Pipeline visuelle 8 nœuds (desktop horizontal + mobile vertical)
[x] Grille métriques 8 cartes compteurs cliquables (filtrage)
[x] 8 composants Step détaillés (formulaires, checklists, StatCards)
[x] Placeholder FortiGate (bouton désactivé + modal saisie manuelle)
[x] Backend stubs 3 endpoints (mock data)
[x] Recherche + filtres par étape + tabs
[x] Notes internes + toggle SMS notification
[x] Bug fix StepGoLive (stepMapping corrigé)
[x] Bug fix payload structure (data nestée correctement)

À faire

[ ] Intégration DB réelle (remplacer mocks par queries SQLAlchemy)
[ ] Machine à états stricte (transitions validées côté backend)
[ ] Intégration FortiGate API (étape 3)
[ ] Upload photo installation (étape 4)
[ ] Appel iperf3 automatique (#79)
[ ] Test session RADIUS réel (étape 6)
[ ] Métriques temps réel depuis DB (étape 7)
[ ] Notifications SMS/email automatiques à chaque transition
[ ] Tests E2E Playwright pour le workflow complet

Dernière mise à jour: 2026-02-22

#56 — Onboarding Revendeur ​

Description ​

Architecture UI ​

Layout principal ​

Pipeline 8 étapes ​

Composants React (12 fichiers) ​

Détail par étape ​

Étape 0 — Candidature (StepCandidature.jsx) ​

Étape 1 — Validation RF (StepRFValidation.jsx) ​

Étape 2 — Contrat (StepContrat.jsx) ​

Étape 3 — VLAN / CPE (StepVlanCpe.jsx) ​

Étape 4 — Installation terrain (StepInstallation.jsx) ​

Étape 5 — Formation (StepFormation.jsx) ​

Étape 6 — Go-Live (StepGoLive.jsx) ​

Étape 7 — Transition (StepTransition.jsx) ​

Endpoints API (Backend Stubs) ​

GET /api/v1/resellers/{reseller_id}/onboarding/details ​

PUT /api/v1/resellers/{reseller_id}/onboarding/step ​

GET /api/v1/onboarding/stats ​

Enums (valeurs exactes) ​

Configuration ​

Intégration FortiGate (Placeholder) ​

Intégration Avec Autres Outils ​

Implémentation ​

Fait ​

À faire ​

#56 — Onboarding Revendeur

Description

Architecture UI

Layout principal

Pipeline 8 étapes

Composants React (12 fichiers)

Détail par étape

Étape 0 — Candidature (`StepCandidature.jsx`)

Étape 1 — Validation RF (`StepRFValidation.jsx`)

Étape 2 — Contrat (`StepContrat.jsx`)

Étape 3 — VLAN / CPE (`StepVlanCpe.jsx`)

Étape 4 — Installation terrain (`StepInstallation.jsx`)

Étape 5 — Formation (`StepFormation.jsx`)

Étape 6 — Go-Live (`StepGoLive.jsx`)

Étape 7 — Transition (`StepTransition.jsx`)

Endpoints API (Backend Stubs)

GET `/api/v1/resellers/{reseller_id}/onboarding/details`

PUT `/api/v1/resellers/{reseller_id}/onboarding/step`

GET `/api/v1/onboarding/stats`

Enums (valeurs exactes)

Configuration

Intégration FortiGate (Placeholder)

Intégration Avec Autres Outils

Implémentation

Fait

À faire