Comment nous avons étendu Medusa pour une place de marché juridique

JuraDocs vend des documents juridiques, mais le vrai produit est la confiance. Un acheteur doit savoir que le vendeur est bien avocat, que le fichier peut être publié sans risque, et qu’un reversement reste explicable si un paiement, un webhook ou un transfert est relancé plus tard. Un backend commerce classique ne garantit pas cela seul.

Medusa nous a donné les produits, paniers, commandes, utilisateurs, stores, workflows et une base admin. JuraDocs avait besoin de la couche métier autour de cette base: permissions par profession, vérification vendeur appuyée sur des registres, accès aux fichiers selon le rôle, partage des frais, registres de reversement, factures et outils opérationnels.

Nous avons donc gardé Medusa comme système commerce sous JuraDocs, puis rendu les concepts de la place de marché juridique explicites au lieu de les cacher dans la metadata produit.

Nous avons gardé le modèle Medusa au lieu de le combattre

La documentation marketplace de Medusa oriente déjà vers des modèles vendeurs personnalisés, des liens entre modules, des routes vendeur protégées et la personnalisation des workflows. Cela correspondait à JuraDocs. Au lieu de forker Medusa, nous avons attaché le domaine JuraDocs aux enregistrements Medusa via des modèles linkables. Les enregistrements commerce restent propres, tout en rendant la propriété vendeur, les permissions et l’état des reversements interrogeables.

Un compte commence comme utilisateur Medusa, parce que l’authentification et l’identité appartiennent toujours à cette couche. Si la profession choisie permet de vendre, le workflow d’inscription crée un profil vendeur, crée un store Medusa, puis relie l’utilisateur au vendeur et au store. Les produits restent des produits Medusa, reliés au store du vendeur. Les commandes restent des commandes Medusa, avec la comptabilité des reversements liée à côté via un lien en lecture seule pour garder la commande claire.

• User vers Vendor: un compte juridique possède un profil vendeur.
• Vendor vers Store: le profil professionnel est relié au store Medusa qui possède les produits.
• Store vers Product: les produits restent des objets catalogue Medusa, avec la propriété vendeur attachée par liens.
• Profession vers Vendor: les professions définissent qui peut vendre, qui peut seulement acheter, et quelles règles de frais s’appliquent.
• VendorShare vers Order et Vendor: les reversements sont suivis hors de la commande, mais reliés à l’événement commerce qui les a créés.

L’inscription est devenue un workflow, pas un formulaire

Un flux d’inscription ordinaire crée un utilisateur, peut-être un profil client, puis s’arrête. JuraDocs prend une décision plus importante dès l’inscription, et c’est la profession qui la décide: ce compte peut-il seulement acheter, ou doit-il aussi devenir vendeur avec un profil vendeur et un store?

Le workflow crée toujours l’utilisateur et un profil client, car même les vendeurs peuvent acheter des documents et le checkout a besoin d’une identité client. Ensuite il lit la profession choisie. Si elle autorise la vente, il crée le profil vendeur, le relie à l’utilisateur, crée un store, puis relie le store au vendeur.

Le profil vendeur porte le numéro d’inscription au barreau et une pièce justificative, à côté des champs société classiques. La vérification compare ensuite ce numéro au registre du barreau. Comme les noms de registres sont rarement propres, chaque association est stockée avec un nom normalisé et des alias connus, afin qu’un vendeur qui saisit le nom un peu différemment puisse tout de même être reconnu.

C’est la différence entre une table de vendeurs et une porte de confiance. JuraDocs doit savoir si quelqu’un a le droit de publier du contenu juridique payant avant que le moindre workflow produit ne s’exécute.

Un document juridique a un cycle de vie

Medusa sait gérer des modèles de commerce digital, mais JuraDocs avait besoin d’un cycle documentaire plus strict. Le fichier source, le fichier traité et le fichier livré à l’acheteur ne sont pas toujours le même objet.

• Les routes d’upload ne signent que les zones attendues, comme les chemins de document original ou anonymisé.
• Le callback d’anonymisation valide la tâche et le token avant d’accepter un résultat de traitement externe.
• Le traitement documentaire peut être terminé, échoué ou encore en cours.
• Le propriétaire peut accéder au fichier côté propriétaire, tandis que l’acheteur reçoit la version publiée ou sûre à télécharger.
• Une route de fichier produit vérifie si le demandeur est propriétaire, acheteur ou en accès produit gratuit avant d’émettre une URL courte durée.

Le dernier point compte beaucoup. Un acheteur ne doit jamais recevoir le document source privé par accident, et le vendeur doit pouvoir inspecter ce qu’il a importé et ce que la plateforme en a préparé. Dans JuraDocs, l’accès au fichier est résolu selon le rôle du demandeur avant toute émission d’URL, et l’URL retournée expire vite.

Le checkout est devenu un règlement conscient du vendeur

Le checkout est l’endroit où les règles JuraDocs se rejoignent, car l’argent bouge et l’acheteur reçoit le document. Le prix peut être le prix affiché ou un prix négocié entre acheteur et vendeur. Avant le paiement, la plateforme vérifie que l’acheteur a droit à ce prix, qu’il ne possède pas déjà le document, et qu’un vendeur n’achète pas son propre travail. Ces règles appartiennent à JuraDocs, donc le checkout les prend directement en charge.

Une fois ces contrôles passés, un clic doit produire trois éléments cohérents: la commande, le paiement Stripe, et un enregistrement par vendeur indiquant ce qui lui est dû. C’est la partie que beaucoup d’articles multi-vendor ignorent. Mettre plusieurs vendeurs sur une page est simple. Faire qu’un achat produise une commande, un débit et des reversements exacts, récupérables en cas d’échec au milieu, c’est le vrai travail.

Les parts vendeur sont devenues le registre de reversement

Nous avons ajouté un modèle de part vendeur parce que la commande ne suffit pas. Une commande dit ce que l’acheteur a acheté. Elle ne donne pas, seule, un registre durable des reversements avec relances, snapshots de frais, IDs de transfert Stripe Connect et état d’échec.

Une part vendeur groupe les données utiles après le checkout: qui a gagné l’argent, quelle commande a créé l’obligation, quels montants brut et net s’appliquent, quels frais marketplace et Stripe ont été retenus, quels IDs de transfert ou de charge appartiennent au paiement, et dans quel état se trouve le reversement s’il faut le relancer ou l’investiguer.

Les helpers de checkout agrègent les montants par vendeur et par devise. Ils figent aussi la configuration des frais pour qu’une ancienne vente ne change pas silencieusement quand quelqu’un modifie les frais de marketplace plus tard. Ce n’est pas le code le plus visible. C’est celui qui rend les reversements explicables.

L’idempotence est entrée dans le design

Le code de paiement est relancé. Les navigateurs réessaient. Les utilisateurs double-cliquent. Les webhooks arrivent plusieurs fois. Les workers peuvent planter au milieu. Si le système ne survit pas à cela, il n’est pas prêt à gérer l’argent d’une marketplace.

Le checkout repose sur des enregistrements d’idempotence: une clé, l’acteur derrière la requête, une manière de comparer le corps de requête, l’état de traitement, la réponse à rejouer, et assez de références pour récupérer la commande ou la session de paiement. Si la même requête revient, le backend peut renvoyer le même résultat. Si la même clé est réutilisée pour une requête différente, il peut rejeter le conflit. Si le traitement devient stale, le système a une voie de récupération au lieu de faire comme si rien ne s’était passé.

Les événements webhook sont aussi enregistrés. Les relances de transfert reposent sur des lectures fraîches, des verrous de traitement, des contrôles d’état succeeded et des clés d’idempotence Stripe déterministes, afin qu’un job répété ne paie pas deux fois un vendeur. Quand les relances sont épuisées, l’échec doit devenir visible pour les opérateurs au lieu de disparaître dans les logs.

• L’idempotence protège le checkout contre les commandes et sessions en double.
• Les enregistrements webhook empêchent les handlers de refaire le même travail deux fois.
• Les verrous de traitement protègent les transferts vendeur contre les workers concurrents.
• L’état de relance et les files d’échec rendent les problèmes de reversement visibles côté opérations.

Le travail admin faisait partie du produit

Pour JuraDocs, les écrans admin sont l’endroit où la plateforme traite la confiance et les exceptions. Cela inclut les utilisateurs gérés, la création vendeur/client, les permissions par profession, les recherches de registre, les états d’alerte, la configuration des factures, les avis, les statistiques, les réglages de traitement documentaire et la visibilité sur les reversements.

C’est une des raisons pour lesquelles le projet ne devrait pas être résumé à un storefront. Le storefront n’est qu’une surface. Les flux admin et opérationnels permettent à l’entreprise de continuer quand un vendeur doit être vérifié, qu’un document doit être relu, qu’un reversement doit être investigué ou qu’une règle de frais doit changer.

Ce que Medusa nous a donné, et ce que nous avons ajouté

Medusa a fourni l’ossature commerce: objets catalogue, paniers, commandes, clients, stores, workflows, modules, liens et une architecture backend extensible sans repartir de zéro.

Nous avons construit la couche JuraDocs: inscription professionnelle, liaison vendeur/store, permissions par profession, traitement des documents juridiques, accès protégé aux fichiers, contrôles d’achat, tableaux de bord vendeur, onboarding Stripe Connect, parts vendeur, transferts relançables, factures, contrôles admin et expérience localisée pour acheteurs et vendeurs.

Le détail important est que ces éléments ne sont pas des fonctionnalités séparées posées autour de l’application. Ils touchent le même flux. La profession d’un vendeur détermine s’il peut vendre. Son profil vendeur détermine la propriété du store. Le store détermine la propriété produit. La propriété produit influence la validation checkout. Le checkout crée les parts vendeur. Les parts vendeur alimentent les reversements, les tableaux de bord, les factures et la récupération admin.

Ce que je dirais à une autre équipe

Si vous utilisez Medusa pour une marketplace, décidez tôt ce qui relève du commerce et ce qui relève de votre domaine. N’attendez pas le checkout pour découvrir que propriété vendeur, frais, permissions, factures et fulfillment ont tous besoin du même concept manquant.

• Rendez la propriété vendeur explicite tôt. Elle réapparaîtra dans les produits, commandes, permissions, dashboards, recherche, frais et factures.
• Utilisez des liens et des modèles de domaine pour les concepts durables. Ne cachez pas tout dans la metadata produit parce que cela semble plus rapide.
• Traitez le succès du paiement comme le début de la comptabilité, pas comme la fin du checkout.
• Figez les frais quand l’argent bouge. Les réglages actuels ne suffisent pas à expliquer d’anciens reversements.
• Construisez les outils admin autour de vrais modes de panne: erreurs de vérification, échecs de traitement documentaire, événements dupliqués, relances de reversement et corrections de facture.
• Pour les documents sensibles, séparez l’accès propriétaire de l’accès acheteur. Le fichier source privé ne doit pas devenir par défaut le fichier acheté.

À retenir

Medusa a fonctionné pour JuraDocs parce qu’il était assez flexible pour rester sous le métier. Nous avons utilisé ses primitives commerce, puis ajouté les modèles de domaine nécessaires à une marketplace juridique: confiance professionnelle, sécurité documentaire, comptabilité vendeur et récupération opérationnelle.

La leçon est simple: Medusa nous a donné la base commerce. JuraDocs est devenue viable quand la confiance, la sécurité documentaire et la comptabilité vendeur sont devenues des concepts métier de premier ordre autour de cette base.