For AI agents: fetch the complete documentation index at /llms.txt, the full documentation corpus at /llms-full.txt, the agent skill at /skill.md, or this page as Markdown at /fr/docs/web/commerce.md (or send Accept: text/markdown).
E-commerce
Produits et commandes du workspace sur un cycle de vie unidirectionnel.
Parcours pas à pas pour débuter
Prérequis : Lisez les deux guides pour débutants ci-dessous, terminez la configuration locale du Web et ouvrez ce monorepo à sa racine dans votre éditeur. Les paramètres Web appartiennent à apps/web/.env.local ; Next.js ne lit pas la racine .env. /dashboard dans le mode faux par défaut est une démo sans base de données ; /auth nécessite une base de données migrée.
Termes rapides : un espace de travail est constitué des utilisateurs, des données et des paramètres distincts d'une équipe. Le serveur est le backend de confiance ; gardez les clés du fournisseur hors du code du navigateur et du téléphone. Une migration est une modification de base de données versionnée qui crée ou met à jour des tables. Un modèle d'IA est le moteur qui répond ; le catalogue de modèles est la liste du serveur des identifiants de modèles et des prix disponibles. Un fournisseur est un service externe tel qu'un service d'IA, de messagerie ou de facturation. Un droit est une subvention qui permet à un espace de travail d'utiliser une fonctionnalité. Un webhook est un message qu'un service envoie au URL d'un autre service.
1. En tant que propriétaire ou administrateur d'un espace de travail, ouvrez /commerce et utilisez le formulaire de produit pour créer une ébauche avec un nom, une devise, un prix unitaire mineur entier et un stock suivi en option (pour USD, 1299 signifie 12,99 $).
2. Activez-le et créez une commande de test locale ; confirmez que le serveur calcule le total et stocke l'instantané du produit.
3. Ne connectez pas un fournisseur de paiement en direct et ne facturez pas un véritable acheteur. Si une commande ne peut pas avancer, vérifiez le stock disponible et l'état de la commande documenté avant de réessayer.
Pour le code personnalisé, commencez par le prompts/README.md fourni et copiez l'invite la plus proche : prompts/new-app-screen.md pour un écran d'application ou prompts/new-landing-page.md pour une page publique. Pour le travail sur un serveur, une base de données ou un fournisseur, confiez à votre agent de codage la tâche de ce guide et demandez-lui de lire les miroirs AGENTS.md, .ai/PROJECT_CONTEXT.md et .ai/ correspondants ; inspectez les fichiers sources exacts nommés ici ; lister les fichiers et les vérifications avant de les modifier ; préserver la propriété de l'espace de travail et les secrets du serveur ; et je vous montre la différence. Indiquez-lui le comportement souhaité, les champs d'entrée et de sortie, les rôles autorisés, les succès et erreurs attendus, ainsi que le compte, le fournisseur ou l'appareil de test. Utilisez des exemples de valeurs ; ne collez jamais un vrai secret.
Gérer les produits et le stock
/commerce fournit aux propriétaires et administrateurs la gestion des produits de l’espace de travail. Les états sont draft/active/archived ; les prix utilisent les unités monétaires mineures et le suivi des stocks est facultatif. La persistance partagée se trouve dans packages/db.
Il s’agit d’un module pour créer un produit. Il n’inclut ni l’achat de ce kit, ni la livraison d’un dépôt source, ni l’exécution des ventes de licences.
Suivre le cycle de vie d’une commande
Les commandes passent de pending à paid puis fulfilled, avec des règles d’annulation, de remise en stock et de remboursement. Le serveur calcule les totaux et conserve un instantané des noms de produits et des prix unitaires pour que les modifications ultérieures d’un produit ne réécrivent pas les commandes passées. Les événements commerce.order_* alimentent les intégrations en aval.
Connectez soigneusement un véritable flux de paiement produit. Un changement d’état effectué par un administrateur ne vérifie ni un paiement ni un remboursement auprès du fournisseur.
Tester le stock et les transitions d’état
Vérifiez le stock insuffisant, les commandes simultanées, la falsification du prix par le client, les transitions arrière invalides, la remise en stock après annulation, le remboursement et l’accès inter-espace de travail.
Configuration et paramètres
La surface /commerce gère un catalogue de produits et des commandes pour le workspace actif. Les produits portent un nom, un slug, un prix en centimes entiers, une devise à trois lettres, une URL d'image optionnelle et un stock suivi optionnel ; les commandes stockent leurs lignes dans commerce_order_item avec des totaux calculés côté serveur.
Le statut de commande n'avance que dans un sens — pending → paid → fulfilled, avec annulation avant paiement et remboursement après. evaluateOrderStatusChange rejette les transitions invalides, inchangées ou interdites, donc une commande annulée ou remboursée ne peut jamais se rouvrir.
/commerce owner/admin console
src/commerce.ts money math + lifecycle
src/commerce-actions.ts owner/admin mutations
commerce_product/order/order_itemProcessus d’implémentation
Seuls owners et admins écrivent — chaque action résout la session et le workspace via requireWorkspaceManager. createCommerceOrderAction valide les lignes (quantités entières de 1 à 9999, produits dupliqués fusionnés), restreint les lignes aux produits actifs, recalcule les totaux côté serveur et maintient une commande sur une seule devise.
Le stock suivi décroît à la création d'une commande et se réapprovisionne à l'annulation ; un champ de stock vide signifie non suivi. La création de commande et chaque changement de statut émettent les webhooks commerce.order_created et commerce.order_status_changed plus des lignes d'audit.
Vérification et dépannage
Vérifiez qu'un membre sous le rôle admin ne peut ni créer de produits ni déplacer de commandes, que les transitions arrière ou latérales sont rejetées, et qu'une commande payée ne peut pas être annulée. Contrôlez que les totaux viennent du serveur — ne faites jamais confiance à un montant fourni par le client — et que le stock revient après une annulation.