Ce document décrit, étape par étape, comment se déroulent les actions importantes dans Shuba. Chaque section explique ce qui se passe « en coulisses » pour que vous compreniez le comportement de l'application.
Flux 1 : Inscription et activation d'un vendeur
Un nouveau vendeur suit ce chemin avant de pouvoir vendre :
- Le futur vendeur crée un compte classique sur la page d'inscription. Son rôle est « Client » par défaut.
- Depuis son tableau de bord, il clique sur « Devenir vendeur » et remplit un formulaire avec le nom de son entreprise et son numéro fiscal.
- Son rôle passe immédiatement à « Vendeur », mais son compte est en attente d'approbation. Il ne peut pas encore publier de produits.
- Un administrateur Shuba reçoit une notification et examine la demande. Il peut approuver ou refuser.
- Une fois approuvé, le vendeur peut créer sa première organisation (boutique) et publier des produits.
Cette double validation (création de compte puis approbation admin) protège la marketplace contre les comptes frauduleux.
Flux 2 : Création d'un produit (wizard 3 étapes)
La création d'un produit est guidée en trois étapes pour éviter les erreurs et simplifier le processus.
Étape 1 : Informations. Le vendeur saisit le nom, la description courte, la description complète, le type de produit (physique, numérique ou service), la catégorie, et les tags. Ces données sont sauvegardées temporairement dans la session du navigateur.
Étape 2 : Prix et stock. Le vendeur définit le prix de vente, un éventuel prix barré, et la quantité en stock. Il peut aussi activer l'option « Gratuit » pour les ressources offertes.
Étape 3 : Images. Le vendeur dépose ses photos (glisser-déposer ou sélection). Les images sont validées immédiatement (format autorisé, taille maximum 5 Mo) puis envoyées vers Supabase Storage. La première image est automatiquement définie comme image principale.
Quand le vendeur clique sur « Créer le produit », les données des trois étapes sont assemblées et le produit est enregistré dans la base de données en une seule opération. Si une étape est manquante, il est redirigé au début.
Flux 3 : Parcours d'achat complet
Le panier : le client ajoute des produits au panier. Pour un visiteur non connecté, il est stocké dans la session du navigateur. Pour un utilisateur connecté, il est sauvegardé dans la base de données (ce qui permet de retrouver son panier en se reconnectant depuis un autre appareil).
La livraison : le client saisit son adresse de livraison (nom, téléphone, rue, ville et pays). Ces informations sont sauvegardées temporairement dans la session jusqu'à la confirmation du paiement.
Le paiement : le client choisit son moyen de paiement (MTN Mobile Money ou Orange Money) et confirme. En production, cela déclenche un appel vers l'API Campay.
La confirmation : une commande est créée. Les fonds sont placés en séquestre. Les articles sont groupés par vendeur, et chaque vendeur reçoit une notification pour préparer sa commande. Le panier est vidé et le client est redirigé vers une page de confirmation.
Flux 4 : Cycle de vie d'un article commandé
Chaque article d'une commande a son propre statut, indépendant des autres articles.
PENDING (en attente de paiement) │ │ paiement confirmé ▼ PAID (fonds en séquestre) │ │ vendeur expédie ▼ SHIPPED (en transit) │ │ vendeur confirme livraison ▼ DELIVERED (livré, en attente de confirmation client) │ │ client confirme réception (avec mot de passe) ▼ COMPLETED (fonds libérés : 95% vendeur, 5% plateforme)
Cas particuliers :
- Si le vendeur n'expédie pas dans les 48 heures, le client peut demander un remboursement.
- Si le client n'a pas confirmé la réception après 7 jours, la commande est validée automatiquement.
- Si un litige est ouvert, la commande passe en statut DISPUTED et les fonds restent gelés jusqu'à résolution.
Flux 5 : Gestion des litiges
Ouverture : depuis la page de détail de sa commande, le client clique sur « Signaler un problème ». Il choisit le type de problème (retard, produit non conforme, refus de livraison, autre) et le décrit en détail.
Gel des fonds : dès que le formulaire est soumis, la commande passe automatiquement en statut DISPUTED. Les fonds sont gelés. Le vendeur et les administrateurs Shuba reçoivent une notification.
Enquête : l'équipe Shuba examine le dossier et fait passer le litige en statut « En enquête ». Elle peut contacter les deux parties.
Résolution : l'équipe clôture le litige avec l'une de ces issues : remboursement accordé au client, livraison confirmée (fonds débloqués au vendeur), ou litige rejeté. Les deux parties reçoivent une notification de la décision.
Flux 6 : Upload et suppression d'images
Lors de l'upload : l'image est d'abord validée côté navigateur (format et taille) pour un retour immédiat. Ensuite, Django la valide une seconde fois côté serveur (vérification des octets réels du fichier). Si tout est correct, elle est envoyée vers Supabase Storage et son chemin est enregistré en base de données.
Lors de la suppression : quand une image est supprimée de la base de données, un signal Django déclenche automatiquement la suppression du fichier dans le bucket Supabase. Cela évite d'accumuler des fichiers inutilisés qui consommeraient de l'espace de stockage.
Lors du remplacement : quand un utilisateur remplace son avatar ou le logo de sa boutique, l'ancienne image est supprimée de Supabase avant que la nouvelle soit enregistrée.
Flux 7 : Suppression d'un compte utilisateur
Vérifications préalables : la suppression est bloquée si l'utilisateur est administrateur, s'il a un litige en cours, ou si une de ses commandes est en cours de traitement.
Confirmation : l'utilisateur doit saisir son adresse email exacte ou le mot « SUPPRIMER » (en majuscules) pour confirmer. Le bouton reste grisé tant que la saisie ne correspond pas.
Désactivation : le compte est désactivé (pas effacé physiquement). L'adresse email est remplacée par une valeur anonyme, les informations personnelles sont effacées. L'avatar est supprimé de Supabase.
Ce qui est conservé : les commandes et transactions restent dans la base pour respecter les obligations légales comptables. Elles sont liées à un compte anonymisé.
Flux 8 : Processus automatiques quotidiens
Un processus planifié exécute chaque jour deux vérifications :
Auto-complétion des livraisons : les articles en statut « Livré » depuis plus de 7 jours sans confirmation du client sont automatiquement validés. Les fonds sont libérés au vendeur.
Alerte d'inactivité vendeur : les articles en statut « Payé » depuis plus de 48 heures sans que le vendeur ait expédié déclenchent une notification au client, lui indiquant qu'il peut demander un remboursement.