Claude Code로 EC 주문용 Azure Service Bus 설계하기

EC 매장에서는 주문 화면, 재고 CSV, 배송 요청, 메일 로그, 재전송 메모가 따로 흩어져 있습니다. 메일만 실패했는데 주문 이벤트 전체를 다시 보내면 재고가 두 번 차감될 수 있습니다. 이 글은 Azure Service Bus를 주문, 재고, 재전송 표로 바꾸는 방법을 다룹니다.

EC 주문 흐름이 깨지는 지점

• 주문 확정, 재고 예약, 배송 요청, 메일 발송, 재전송을 하나의 queue에 섞지 않습니다.
• 주문 하나를 재고, 배송, 메일, 분석으로 나눌 때 topic을 씁니다.
• MessageId는 주문 ID, 라인 ID, action으로 안정적으로 만듭니다.
• dead-letter queue는 확인 장소이지 무조건 재전송 버튼이 아닙니다.
• Claude Code는 표를 만들고, 결제, 환불, 개인정보, 승인 판단은 사람이 봅니다.

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.

Claude Code 범위와 사람이 보는 범위

EC 매장에서는 주문 화면, 재고 CSV, 배송 요청, 메일 로그, 재전송 메모가 따로 흩어져 있습니다. 메일만 실패했는데 주문 이벤트 전체를 다시 보내면 재고가 두 번 차감될 수 있습니다. 이 글은 Azure Service Bus를 주문, 재고, 재전송 표로 바꾸는 방법을 다룹니다. 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.

세 가지 Use case

Use case 1

주문 확정은 여러 작업을 시작합니다. 입력: 주문 CSV, 주문 ID, 라인 ID, SKU, 수량, 결제 상태, 메일 플래그. 출력: topic:orders와 재고, 배송, 메일 subscription. 사람 확인: 미결제, 예약상품, 묶음상품, 선물, 수동 재고 조정, 메일 문구.

Use case 2

재고 예약에는 안정적인 업무 키가 필요합니다. 입력: 주문 ID, 라인 ID, SKU, 수량, reserve action, 송신 로그. 출력: 주문 ID plus 라인 ID plus reserve 형태의 MessageId 표. 사람 확인: 수량 변경, 취소, 재주문, 세트 분해, 재고 복구.

Use case 3

DLQ는 운영팀도 읽을 수 있어야 합니다. 입력: reason, description, 주문 ID, SKU, 실패 횟수, 시간, 메모. 출력: 자동 retry, 수정 후 retry, 주문 보류, 환불 확인, 개발 조사. 사람 확인: 고객 안내, 환불, 재고 차이, 창고 연락, 권한.

복사해서 쓰는 프롬프트

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.

확인 코드

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: 흔한 실수

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.

자주 묻는 질문

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.

상담으로 이어지는 길

EC 팀의 가치는 클라우드 그림보다 잘못된 재고, 배송 지연, 문의를 줄이는 데 있습니다. CSV 컬럼, 실패 3건, 현재 재전송 절차를 상담 페이지에 가져오면 됩니다. Use Claude Code training and consultation when the team needs help turning order CSV, inventory CSV, retry logs, and release approval into a workflow.

확인한 내용

Microsoft Learn의 Service Bus overview, queues/topics/subscriptions, DLQ, duplicate detection, transfers, pricing tiers를 확인했습니다. 로컬 코드는 주문 ID 누락, 중복 MessageId, 알 수 없는 route를 표시합니다. 첫 행동은 주문, 재고, 메일, 재전송 표를 만드는 것입니다.