Concevoir Azure Service Bus pour les commandes EC avec Claude Code

Où le flux EC casse

Ne mélangez pas commande, stock, expédition, email et retry dans une seule queue.
Utilisez un topic quand une commande doit alimenter stock, expédition, email et analyse.
Préparez un MessageId stable avec commande, ligne et action.
La dead-letter queue est un bureau d’inspection, pas un bouton de renvoi aveugle.
Claude Code prépare les tableaux; paiement, remboursement, données personnelles et approbation restent humains.

The Microsoft documentation for Service Bus overview, queues, topics, and subscriptions, dead-letter queues, duplicate detection, message transfers, and pricing tiers is the source base. The internal Azure memo pattern is also related to the Azure OpenAI privacy memo.

Ce que Claude Code prépare et ce que l’humain valide

Dans une boutique EC, l’écran de commande, le CSV de stock, la demande d’expédition, le journal email et la note de retry sont souvent séparés. Si l’on renvoie tout l’événement alors que seul l’email a échoué, le stock peut être réservé deux fois. Cet article transforme Azure Service Bus en mémo lisible. Claude Code should read column names, event names, retry samples, and DLQ reason text. It should not receive card data, full address text, refund judgment, or credentials. The output should be a table with event name, input columns, queue or topic, subscription, MessageId, DLQ owner, retry condition, and human review.

Humans keep payment state, refund permission, privacy policy, stock finalization, warehouse contract, apology text, and release approval. This split matters because a technically valid retry can still be a business mistake. The table makes the stop point visible before production.

Trois cas d’usage

Use case 1

La commande acceptée déclenche plusieurs travaux. Entrée: CSV, id commande, ligne, SKU, quantité, paiement, email. Sortie: topic:orders avec subscriptions stock, expédition, email, analyse. Contrôle humain: impayé, précommande, lot, cadeau, ajustement manuel, texte email.

Use case 2

La réservation de stock demande une clé stable. Entrée: id commande, ligne, SKU, quantité, action reserve, journal d’envoi. Sortie: table MessageId comme commande plus ligne plus reserve. Contrôle humain: changement de quantité, annulation, nouvelle commande, lot, retour stock.

Use case 3

La DLQ doit être lisible par l’exploitation. Entrée: reason, description, id commande, SKU, nombre d’échecs, heure, mémo. Sortie: retry auto, corriger puis renvoyer, bloquer commande, vérifier remboursement, enquête dev. Contrôle humain: client, remboursement, écart de stock, entrepôt, autorisation.

Prompt à copier

You are preparing an Azure Service Bus design memo for an EC store.
Inputs: order CSV columns, inventory CSV columns, event names, retry logs, DLQ reason samples, and planned Azure tier.
Output:
1. Event table with eventName, input columns, queue or topic, subscription, MessageId, and DLQ owner.
2. Human review table for payment, refund, personal data, stock finalization, customer notice, and resend approval.
3. MessageId naming rules based on order id, line item id, and action.
4. DLQ classification: auto retry, fix then retry, hold order, refund review, engineering investigation.
5. One first action that can be done in 30 minutes.
Rules: do not put card data or full address text in messages. Do not blindly resend every DLQ message.

Code de vérification

const events = [
  { type: "order.accepted", orderId: "ORD-1001", lineItemId: "1", sku: "TSHIRT-M", quantity: 2, action: "accept" },
  { type: "inventory.reserve", orderId: "ORD-1001", lineItemId: "1", sku: "TSHIRT-M", quantity: 2, action: "reserve" },
  { type: "inventory.reserve", orderId: "ORD-1001", lineItemId: "1", sku: "TSHIRT-M", quantity: 2, action: "reserve" },
  { type: "mail.send", orderId: "ORD-1001", lineItemId: "", sku: "", quantity: 0, action: "confirmation" },
  { type: "inventory.reserve", orderId: "", lineItemId: "2", sku: "MUG-BLUE", quantity: 1, action: "reserve" },
  { type: "shipping.requested", orderId: "ORD-1002", lineItemId: "1", sku: "BAG-BK", quantity: 1, action: "ship" }
];

function routeEvent(event) {
  if (event.type === "order.accepted") {
    return {
      entity: "topic:orders",
      messageId: event.orderId + ":accepted",
      reason: "fan out to inventory, shipping, mail, and analytics subscriptions"
    };
  }
  if (event.type === "inventory.reserve") {
    return {
      entity: "queue:inventory-reserve",
      messageId: event.orderId + ":" + event.lineItemId + ":reserve",
      reason: "one stock reservation worker should own this line item"
    };
  }
  if (event.type === "mail.send") {
    return {
      entity: "queue:mail-send",
      messageId: event.orderId + ":" + event.action,
      reason: "mail can retry without touching stock"
    };
  }
  return {
    entity: "needs-design-review",
    messageId: event.orderId + ":" + event.type,
    reason: "route is not documented yet"
  };
}

const seen = new Set();
const findings = [];

for (const event of events) {
  const route = routeEvent(event);
  if (!event.orderId) {
    findings.push({
      type: "missing-order-id",
      eventType: event.type,
      fix: "do not send this message until the order id is present"
    });
  }
  if (seen.has(route.messageId)) {
    findings.push({
      type: "duplicate-message-id",
      eventType: event.type,
      messageId: route.messageId,
      fix: "keep the same MessageId for sender retry, but make the handler idempotent"
    });
  }
  if (route.entity === "needs-design-review") {
    findings.push({
      type: "unknown-route",
      eventType: event.type,
      fix: "decide queue, topic subscription, DLQ owner, and retry rule before release"
    });
  }
  seen.add(route.messageId);
}

console.table(findings);
if (findings.length > 0) process.exitCode = 1;

Pitfall: erreurs fréquentes

The first cause is one queue for every action. The fix is to use a topic for order accepted and separate queues or subscriptions for inventory, shipping, and mail. This prevents a mail retry from touching stock again.

The second cause is random MessageId generation. The fix is to generate the id from order id, line item id, and action before sending. Duplicate detection can only help inside the configured window when the id stays stable.

The third cause is blind DLQ resend. The fix is to classify each reason into auto retry, fix then retry, hold order, refund review, or engineering investigation. Messages that affect customers or refunds need human review.

The fourth cause is ignoring tier differences. The fix is to check whether topics, transactions, de-duplication, or sessions are required before choosing Basic, Standard, or Premium.

Questions fréquentes

Q. Should every EC event be a topic? A. No. Topic is useful when one event fans out. A queue is clearer when one worker owns one task such as inventory reservation or mail send.

Q. Does duplicate detection remove all double stock moves? A. No. It helps when MessageId is stable. The handler should still check whether the line item was already processed.

Q. Who should read DLQ? A. Operations and developers. EC failures can involve customer notice, refund, stock gap, and warehouse contact.

Q. What should message body contain? A. Prefer order id, line item id, SKU, quantity, and reference id. Review personal data and logging policy before adding sensitive text.

Chemin vers la consultation

Pour une équipe EC, la valeur vient de moins de stock faux, moins de retards et moins de tickets. Apportez colonnes CSV, trois échecs et procédure de retry à la page consultation. Use Claude Code training and consultation when the team needs help turning order CSV, inventory CSV, retry logs, and release approval into a workflow.

Ce que j’ai vérifié

J’ai vérifié les pages Microsoft Learn sur Service Bus, queues/topics/subscriptions, DLQ, duplicate detection, transfers et pricing. Le code local signale id commande manquant, MessageId dupliqué et route inconnue. Le premier geste est une table commande, stock, email et retry.