Pub/Sub für Logistik-Verzögerungen: Claude-Code-Review

In einem Logistikunternehmen kann eine kleine ETA-Änderung im Dispositionsplan E-Mail, LINE, Kundenportal und Support-Hinweis auslösen. Wenn der Pub/Sub-Consumer nach dem Versand, aber vor dem Ack abstürzt, kann dieselbe Nachricht erneut kommen. Der Kunde sieht zwei Verzögerungsmeldungen und fragt, welche Ankunftszeit stimmt. Dieser Artikel macht daraus einen Claude-Code-Prüfablauf.

Kernpunkte

Pub/Sub-Design in der Logistik beginnt mit der Kundenkommunikation. Erst wird entschieden, welche ETA-Änderung nach außen geht, welche nur den Bildschirm aktualisiert und welche eine Person prüfen muss. Claude Code entwirft Tabellen; Menschen prüfen Vertrag, Entschuldigung, Datenschutz und Ausnahmen.

Workflow Before Pub/Sub Settings

Vor Subscription-Einstellungen wird der Weg vom Dispositions-CSV bis zur Kundennachricht gezeichnet. Die Tabelle enthält shipmentId, Status, ETA, Kanal, Template, Retry Count und Reviewer. So sinken doppelte Nachrichten, Rückfragen und manuelle Klärungszeit.

Area	What Claude Code drafts	Human review
Delay event	payload fields, topic name, sample messages	shipper promise, delay reason, personal data
Notification send	idempotency key, retry rule, audit log	customer channel, template wording, compensation
DLQ review	alert fields, replay checklist, owner	whether the notice is still useful
Metrics	duplicate count, DLQ age, customer calls	revenue impact and consultation priority

3 Use Cases

Use case 1: Define delay events

Nutze reale Artefakte: Dispositionsboard, Kundenportal, Verzögerungsgründe und Nachrichtenvorlagen. Claude Code markiert, welche Events nach außen gehen dürfen.

• Input: dispatch CSV columns, ETA changes, delay reasons, customer channel settings.
• Output: event names, payload fields, and send rules for customer notices.
• Human review: check contract wording, customer impact, personal data, and timing.

Use case 2: Stop duplicate notices

Use an idempotency key built from shipmentId, status, ETA, channel, and templateId. Pub/Sub may redeliver messages when ack timing is unclear, so the notification worker needs its own gate before email, LINE, or dashboard history is written.

• Input: shipment ID, notification history, retry count, previous ETA, new ETA.
• Output: duplicate detection rule, skip rule, audit log fields.
• Human review: decide whether a changed ETA means a new notice or a correction.

Use case 3: Make DLQ visible to operations

Dead-letter topics should not become an engineer-only storage area. For logistics teams, a DLQ item may mean that a customer did not receive a delay notice. The operations screen should show shipment ID, oldest age, last error, owner, and whether a manual call already happened.

• Input: retry count, last error, payload reference, customer account, owner.
• Output: DLQ triage table, replay rule, manual contact checklist.
• Human review: decide whether replaying the notice still helps the customer.

Copy-Paste Prompt

Act as a German logistics Pub/Sub notification reviewer.
Goal: prevent duplicate delay notices, stale ETA messages, and forgotten DLQ items.

Review these materials:
- dispatch CSV columns
- delay notice templates
- Pub/Sub topic and subscription names
- retry policy draft
- dead-letter topic draft
- customer notification channels

Return:
1. event names and payload fields
2. idempotency key proposal
3. retryable and non-retryable failure classes
4. DLQ triage table for operations
5. ten test events before production

Rules:
- do not expose customer phone numbers or driver personal data in payloads
- do not send stale ETA notices
- do not send the same idempotency key twice
- send compensation, apology, and contract questions to humans

Working Check Code

// verify-logistics-pubsub.mjs
// No dependencies. Run with: node verify-logistics-pubsub.mjs
const events = [
  {
    shipmentId: "S-1001",
    sequence: 12,
    status: "delayed",
    previousEta: "2026-07-19T16:30:00+09:00",
    eta: "2026-07-19T17:10:00+09:00",
    idempotencyKey: "S-1001:delayed:2026-07-19T17:10:00+09:00",
    channel: "line",
    retryCount: 0,
    dlqTopic: "delay-notice-dlq",
    reviewer: "cs-lead"
  },
  {
    shipmentId: "S-1001",
    sequence: 12,
    status: "delayed",
    previousEta: "2026-07-19T16:30:00+09:00",
    eta: "2026-07-19T17:10:00+09:00",
    idempotencyKey: "S-1001:delayed:2026-07-19T17:10:00+09:00",
    channel: "line",
    retryCount: 1,
    dlqTopic: "delay-notice-dlq",
    reviewer: "cs-lead"
  },
  {
    shipmentId: "S-1002",
    sequence: 5,
    status: "delayed",
    previousEta: "2026-07-19T18:20:00+09:00",
    eta: "2026-07-19T18:00:00+09:00",
    idempotencyKey: "S-1002:delayed:2026-07-19T18:00:00+09:00",
    channel: "email",
    retryCount: 4,
    dlqTopic: "",
    reviewer: ""
  }
];

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

for (const event of events) {
  if (seen.has(event.idempotencyKey)) {
    problems.push({
      shipmentId: event.shipmentId,
      reason: "duplicate idempotency key",
      fix: "publish the retry, but skip customer notification"
    });
  }
  seen.add(event.idempotencyKey);

  if (new Date(event.eta) <= new Date(event.previousEta)) {
    problems.push({
      shipmentId: event.shipmentId,
      reason: "ETA did not move later",
      fix: "do not send a delay notice; send to human review"
    });
  }

  if (event.retryCount >= 3 && !event.dlqTopic) {
    problems.push({
      shipmentId: event.shipmentId,
      reason: "retry limit reached without DLQ",
      fix: "route to delay-notice-dlq and alert the CS lead"
    });
  }

  if (!event.reviewer) {
    problems.push({
      shipmentId: event.shipmentId,
      reason: "missing reviewer",
      fix: "require a dispatcher or CS lead before customer send"
    });
  }
}

if (problems.length > 0) {
  console.table(problems);
  process.exitCode = 1;
} else {
  console.log("Pub/Sub delay notification checklist passed.");
}

Pitfall: Common Failure Cases

Der typische Fehler ist die Vermischung von technischer Wiederzustellung und geschäftlicher Benachrichtigung. Pub/Sub darf erneut liefern; der Kunde darf nicht denselben Hinweis doppelt erhalten.

First, teams confuse transport retry with customer retry. Pub/Sub can redeliver a message, but the customer should not receive the same email twice. The fix is an idempotency key stored by the notification service.

Second, teams rely on ordering alone. Ordering keys help, but the application still needs to reject old sequence numbers and stale ETAs before external sending.

Third, DLQ is left inside engineering tools. In logistics, that hides a customer communication gap. Move DLQ age and owner into the operations routine.

FAQ

F. Reicht exactly-once delivery gegen doppelte Nachrichten?\n\nA. Nein. Vor E-Mail, LINE oder Portal-Historie braucht der Dienst eine gespeicherte Idempotency-Key-Prüfung.

Q. Should Pub/Sub messageId be the idempotency key?

A. Usually no. A logistics notice should use business fields such as shipmentId, status, ETA, channel, and templateId so that the same customer-facing notice is recognized even when publishing changes.

Q. Can DLQ messages be replayed in bulk?

A. Not without a human check. A delay notice may become useless after delivery, so replay should inspect current ETA, delivery status, and manual contact history.

Q. Where should readers go next?

A. Teams that need Pub/Sub, Cloud Run, IAM, notification templates, and operational checks reviewed together should start from ClaudeCodeLab training.

What I Verified

Für die deutsche Fassung habe ich Logistikprozesse, Duplicate Notices, DLQ-Sichtbarkeit und den Beratungslink geprüft. I checked the official Google Cloud pages for Pub/Sub overview, subscriptions, retry policy, dead-letter topics, exactly-once delivery, and message ordering. I also checked that this article has one CTA, an internal link, external sources, executable JavaScript, and locale files.