Développement du Backend Medusa

Guide complet du développement backend pour les applications Medusa. Contient des motifs répartis sur 6 catégories couvrant l'architecture, la sécurité des types, le placement de la logique métier et les pièges courants.

Quand appliquer

Chargez cette skill pour TOUTE tâche de développement backend, notamment :

Créer ou modifier des modules et modèles de données personnalisés
Implémenter des workflows pour les mutations
Construire des routes API (store ou admin)
Définir des module links entre entités
Écrire de la logique métier ou une validation
Interroger des données entre modules
Implémenter l'authentification/autorisation

Chargez également ces skills quand :

building-admin-dashboard-customizations : Créer une UI admin (widgets, pages, formulaires)
building-storefronts : Appeler les routes API du backend depuis des storefronts (intégration SDK)

CRITIQUE : Charger les fichiers de référence si nécessaire

La référence rapide ci-dessous ne suffit PAS pour l'implémentation. Vous DEVEZ charger les fichiers de référence pertinents avant d'écrire du code pour ce composant.

Chargez ces références selon ce que vous implémentez :

Créer un module ? → DEVEZ charger reference/custom-modules.md en premier
Créer des workflows ? → DEVEZ charger reference/workflows.md en premier
Créer des routes API ? → DEVEZ charger reference/api-routes.md en premier
Créer des module links ? → DEVEZ charger reference/module-links.md en premier
Interroger des données ? → DEVEZ charger reference/querying-data.md en premier
Ajouter l'authentification ? → DEVEZ charger reference/authentication.md en premier

Exigence minimale : Chargez au moins 1-2 fichiers de référence pertinents à votre tâche spécifique avant l'implémentation.

Motif critique de l'architecture

SUIVEZ TOUJOURS ce flux - ne contournez jamais les couches :

Module (modèles de données + opérations CRUD)
  ↓ utilisé par
Workflow (logique métier + mutations avec rollback)
  ↓ exécuté par
API Route (interface HTTP, middleware de validation)
  ↓ appelé par
Frontend (tableau de bord admin/storefront via SDK)

Conventions clés :

Seulement GET, POST, DELETE (jamais PUT/PATCH)
Les workflows sont requis pour TOUTES les mutations
La logique métier appartient aux étapes de workflow, PAS aux routes
Interrogez avec query.graph() pour la récupération de données entre modules
Interrogez avec query.index() (Index Module) pour filtrer sur des modules séparés avec des liens
Les module links maintiennent l'isolation entre modules

Catégories de règles par priorité

Priorité	Catégorie	Impact	Préfixe
1	Violations d'architecture	CRITIQUE	`arch-`
2	Sécurité des types	CRITIQUE	`type-`
3	Placement de la logique métier	HAUTE	`logic-`
4	Imports et organisation du code	HAUTE	`import-`
5	Motifs d'accès aux données	MOYEN (inclut règle de prix CRITIQUE)	`data-`
6	Organisation des fichiers	MOYEN	`file-`

Référence rapide

1. Violations d'architecture (CRITIQUE)

arch-workflow-required - Utilisez des workflows pour TOUTES les mutations, jamais appeler les services de modules directement depuis les routes
arch-layer-bypass - Ne contournez jamais les couches (route → service sans workflow)
arch-http-methods - Utilisez seulement GET, POST, DELETE (jamais PUT/PATCH)
arch-module-isolation - Utilisez les module links, pas les appels de services entre modules directs
arch-query-config-fields - Ne définissez pas fields explicitement quand vous utilisez req.queryConfig

2. Sécurité des types (CRITIQUE)

type-request-schema - Passez le type déduit Zod à MedusaRequest<T> quand vous utilisez req.validatedBody
type-authenticated-request - Utilisez AuthenticatedMedusaRequest pour les routes protégées (pas MedusaRequest)
type-export-schema - Exportez le schéma Zod ET le type déduit depuis les middlewares
type-linkable-auto - N'ajoutez jamais .linkable() aux modèles de données (automatiquement ajouté)
type-module-name-camelcase - Les noms de modules DOIVENT être camelCase, jamais utiliser de tirets (provoque des erreurs d'exécution)

3. Placement de la logique métier (HAUTE)

logic-workflow-validation - Mettez la validation métier dans les étapes de workflow, pas dans les routes API
logic-ownership-checks - Validez la propriété/permissions dans les workflows, pas dans les routes
logic-module-service - Gardez les modules simples (CRUD seulement), mettez la logique dans les workflows

4. Imports et organisation du code (HAUTE)

import-top-level - Importez les workflows/modules en haut du fichier, jamais utiliser await import() dans le corps de la route
import-static-only - Utilisez les imports statiques pour toutes les dépendances
import-no-dynamic-routes - Les imports dynamiques ajoutent une surcharge et cassent la vérification de type

5. Motifs d'accès aux données (MOYEN)

data-price-format - CRITIQUE : Les prix sont stockés en l'état dans Medusa (49.99 stocké comme 49.99, PAS en centimes). Ne multipliez jamais par 100 au moment de l'enregistrement ou divisez par 100 au moment de l'affichage
data-query-method - Utilisez query.graph() pour récupérer les données ; utilisez query.index() (Index Module) pour filtrer sur les modules liés
data-query-graph - Utilisez query.graph() pour les requêtes entre modules avec notation pointée (sans filtrage entre modules)
data-query-index - Utilisez query.index() lors du filtrage par propriétés de modèles de données liés dans des modules séparés
data-list-and-count - Utilisez listAndCount pour les requêtes paginées d'un seul module
data-linked-filtering - query.graph() ne peut pas filtrer par champs de modules liés - utilisez query.index() ou interrogez à partir de cette entité directement
data-no-js-filter - N'utilisez pas JavaScript .filter() sur les données liées - utilisez les filtres de base de données (query.index() ou interrogez l'entité)
data-same-module-ok - Vous pouvez filtrer par relations du même module avec query.graph() (p. ex., product.variants)
data-auth-middleware - Faites confiance au middleware authenticate, ne vérifiez pas manuellement req.auth_context

6. Organisation des fichiers (MOYEN)

file-workflow-steps - Recommandé : Créez les étapes dans src/workflows/steps/[name].ts
file-workflow-composition - Les fonctions de composition dans src/workflows/[name].ts
file-middleware-exports - Exportez les schémas et types depuis les fichiers middleware
file-links-directory - Définissez les module links dans src/links/[name].ts

Règles de composition du workflow

La fonction workflow a des contraintes critiques :

// ✅ CORRECT
const myWorkflow = createWorkflow(
  "name",
  function (input) { // Fonction régulière, pas async, pas arrow
    const result = myStep(input) // Sans await
    return new WorkflowResponse(result)
  }
)

// ❌ FAUX
const myWorkflow = createWorkflow(
  "name",
  async (input) => { // ❌ Pas async, pas les arrow functions
    const result = await myStep(input) // ❌ Pas d'await
    if (input.condition) { /* ... */ } // ❌ Pas de conditionnelles
    return new WorkflowResponse(result)
  }
)

Contraintes :

Pas async/await (s'exécute au moment du chargement)
Pas les arrow functions (utilisez function)
Pas de conditionnelles/ternaires (utilisez when())
Pas de manipulation de variables (utilisez transform())
Pas de création de date (utilisez transform())
Les appels à plusieurs étapes ont besoin de .config({ name: "unique-name" }) pour éviter les conflits

Checklist des erreurs courantes

Avant l'implémentation, vérifiez que vous ne faites PAS ceci :

Architecture :

[ ] Appeler les services de modules directement depuis les routes API
[ ] Utiliser les méthodes PUT ou PATCH
[ ] Contourner les workflows pour les mutations
[ ] Définir fields explicitement avec req.queryConfig
[ ] Sauter les migrations après la création de module links

Sécurité des types :

[ ] Oublier l'argument de type MedusaRequest<SchemaType>
[ ] Utiliser MedusaRequest à la place de AuthenticatedMedusaRequest pour les routes protégées
[ ] Ne pas exporter le type déduit Zod depuis les middlewares
[ ] Ajouter .linkable() aux modèles de données
[ ] Utiliser des tirets dans les noms de modules (doit être camelCase)

Logique métier :

[ ] Valider les règles métier dans les routes API
[ ] Vérifier la propriété dans les routes au lieu des workflows
[ ] Vérifier manuellement req.auth_context?.actor_id quand le middleware a déjà été appliqué

Imports :

[ ] Utiliser await import() dans les corps des gestionnaires de route
[ ] Les imports dynamiques pour les workflows ou modules

Accès aux données :

[ ] CRITIQUE : Multiplier les prix par 100 au moment de l'enregistrement ou diviser par 100 au moment de l'affichage (les prix sont stockés en l'état : $49.99 = 49.99)
[ ] Filtrer par champs de modules liés avec query.graph() (utilisez query.index() ou interrogez à partir de l'autre côté à la place)
[ ] Utiliser JavaScript .filter() sur les données liées (utilisez query.index() ou interrogez l'entité liée directement)
[ ] Ne pas utiliser query.graph() pour la récupération de données entre modules
[ ] Utiliser query.graph() quand vous avez besoin de filtrer sur des modules séparés (utilisez query.index() à la place)

Valider l'implémentation

CRITIQUE : Exécutez toujours la commande de build après l'implémentation pour détecter les erreurs de type et les problèmes d'exécution.

Quand valider

Après l'implémentation de toute nouvelle fonctionnalité
Après les modifications apportées à des modules, workflows ou routes API
Avant de marquer les tâches comme complètes
De manière proactive, sans attendre que l'utilisateur demande

Comment exécuter le build

Détectez le gestionnaire de packages et exécutez la commande appropriée :

npm run build      # ou pnpm build / yarn build

Gestion des erreurs de build

Si la build échoue :

Lisez attentivement les messages d'erreur
Corrigez les erreurs de type, les problèmes d'imports et les erreurs de syntaxe
Exécutez la build à nouveau pour vérifier la correction
NE marquez PAS l'implémentation comme complète tant que la build ne réussit pas

Erreurs de build courantes :

Imports ou exports manquants
Incompatibilités de type (p. ex., argument de type MedusaRequest<T> manquant)
Composition incorrecte du workflow (fonctions async, conditionnelles)

Étapes suivantes - Tester votre implémentation

Après l'implémentation réussie d'une fonctionnalité, fournissez toujours ces étapes suivantes à l'utilisateur :

1. Démarrer le serveur de développement

Si le serveur n'est pas déjà en cours d'exécution, démarrez-le :

npm run dev      # ou pnpm dev / yarn dev

2. Accéder au tableau de bord admin

Ouvrez votre navigateur et accédez à :

Tableau de bord admin : http://localhost:9000/app

Connectez-vous avec vos identifiants admin pour tester les fonctionnalités liées à l'admin.

3. Tester les routes API

Si vous avez implémenté des routes API personnalisées, listez-les pour que l'utilisateur les teste :

Routes admin (requièrent l'authentification) :

POST http://localhost:9000/admin/[your-route] - Description de ce qu'elle fait
GET http://localhost:9000/admin/[your-route] - Description de ce qu'elle fait

Routes store (publiques ou authentifiées par client) :

POST http://localhost:9000/store/[your-route] - Description de ce qu'elle fait
GET http://localhost:9000/store/[your-route] - Description de ce qu'elle fait

Exemple de test avec cURL :

# Route admin (nécessite l'authentification)
curl -X POST http://localhost:9000/admin/reviews/123/approve \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  --cookie "connect.sid=YOUR_SESSION_COOKIE"

# Route store
curl -X POST http://localhost:9000/store/reviews \
  -H "Content-Type: application/json" \
  -d '{"product_id": "prod_123", "rating": 5, "comment": "Great product!"}'

4. Étapes de test supplémentaires

Selon ce qui a été implémenté, mentionnez :

Workflows : Testez les opérations de mutation et vérifiez le rollback en cas d'erreurs
Subscribers : Déclenchez les événements et vérifiez les logs pour l'exécution des subscribers
Tâches planifiées : Attendez l'exécution de la tâche ou consultez les logs pour la sortie cron

Format pour présenter les étapes suivantes

Présentez toujours les étapes suivantes dans un format clair et réalisable après l'implémentation :

## Implémentation complète

La [feature name] a été implémentée avec succès. Voici comment la tester :

### Démarrer le serveur de développement
[commande de démarrage du serveur en fonction du gestionnaire de packages]

### Accéder au tableau de bord admin
Ouvrez http://localhost:9000/app dans votre navigateur

### Tester les routes API
J'ai ajouté les routes suivantes :

**Routes admin :**
- POST /admin/[route] - [description]
- GET /admin/[route] - [description]

**Routes store :**
- POST /store/[route] - [description]

### Quoi tester
1. [Cas de test spécifique 1]
2. [Cas de test spécifique 2]
3. [Cas de test spécifique 3]

Comment utiliser

Pour les motifs détaillés et les exemples, chargez les fichiers de référence :

reference/custom-modules.md    - Créer des modules avec modèles de données
reference/workflows.md          - Création de workflows et motifs d'étapes
reference/api-routes.md         - Structure des routes API et validation
reference/module-links.md       - Lier les entités entre modules
reference/querying-data.md      - Motifs de requête et règles de filtrage
reference/authentication.md     - Protéger les routes et accéder aux utilisateurs
reference/error-handling.md     - Types MedusaError et motifs
reference/scheduled-jobs.md     - Tâches cron et tâches périodiques
reference/subscribers-and-events.md - Gestion des événements
reference/troubleshooting.md    - Erreurs courantes et solutions

Chaque fichier de référence contient :

Listes de contrôle d'implémentation étape par étape
Exemples de code correct vs incorrect
Motifs TypeScript et sécurité des types
Pièges courants et solutions

Quand utiliser cette skill vs serveur MCP MedusaDocs

⚠️ CRITIQUE : Cette skill doit être consultée EN PREMIER pour la planification et l'implémentation.

Utilisez cette skill pour (SOURCE PRIMAIRE) :

Planification - Comprendre comment structurer les fonctionnalités backend Medusa
Architecture - Motifs Module → Workflow → API Route
Bonnes pratiques - Motifs de code correct vs incorrect
Règles critiques - Ce qu'il ne faut PAS faire (erreurs courantes et anti-motifs)
Motifs d'implémentation - Guides étape par étape avec listes de contrôle

Utilisez le serveur MedusaDocs MCP pour (SOURCE SECONDAIRE) :

Signatures de méthodes spécifiques après avoir identifié la méthode à utiliser
Options de configuration du module intégré
Définitions de type officielles
Détails de configuration au niveau du framework

Pourquoi les skills viennent d'abord :

Les skills contiennent des conseils d'opinion et des anti-motifs que le MCP n'a pas
Les skills montrent les motifs architecturaux nécessaires à la planification
Le MCP est un matériel de référence ; les skills sont des conseils normatifs

Intégration avec les applications frontend

⚠️ CRITIQUE : Les applications frontend DOIVENT utiliser le SDK Medusa JS pour TOUTES les requêtes API

Lors de la construction de fonctionnalités qui s'étendent du backend au frontend :

Pour le tableau de bord admin :

Backend (cette skill) : Module → Workflow → API Route
Frontend : Chargez la skill building-admin-dashboard-customizations
Connexion :
- Endpoints intégrés : Utilisez les méthodes SDK existantes (sdk.admin.product.list())
- Routes API personnalisées : Utilisez sdk.client.fetch("/admin/my-route")
- JAMAIS utiliser fetch() régulier - les en-têtes d'authentification manquants provoquent des erreurs

Pour les storefronts :

Backend (cette skill) : Module → Workflow → API Route
Frontend : Chargez la skill building-storefronts
Connexion :
- Endpoints intégrés : Utilisez les méthodes SDK existantes (sdk.store.product.list())
- Routes API personnalisées : Utilisez sdk.client.fetch("/store/my-route")
- JAMAIS utiliser fetch() régulier - la clé API publiable manquante provoque des erreurs

Pourquoi le SDK est obligatoire :

Les routes store ont besoin de l'en-tête x-publishable-api-key
Les routes admin ont besoin des en-têtes Authorization et session
Le SDK gère automatiquement tous les en-têtes requis
fetch() régulier sans en-têtes → erreurs d'authentification/autorisation

Consultez les skills frontend respectives pour les motifs d'intégration complets.

building-with-medusa