Pub/Sub pour avis de retard logistique: revue Claude Code

Dans une société de transport, une ETA modifiée dans le tableau de dispatch peut déclencher un e-mail, LINE, l’historique du portail et une action du support. Si le consommateur Pub/Sub tombe après l’envoi mais avant l’ack, le message peut revenir. Le client reçoit deux avis de retard et ne sait plus lequel croire. Cet article transforme ce risque en revue Claude Code concrète.

Points clés

Le design Pub/Sub pour la logistique commence par la promesse client. Il faut séparer changement d’état, avis externe, historique interne et cas à valider par une personne. Claude Code peut rédiger la carte des événements; l’équipe valide contrat, excuses, compensation et données personnelles.

Workflow Before Pub/Sub Settings

Avant de régler la subscription, trace le chemin depuis le CSV de dispatch jusqu’au message client. Le tableau doit montrer shipmentId, statut, ETA, canal, template, nombre de retry et relecteur. L’objectif métier est simple: moins de doublons, moins d’appels, plus de contrôle.

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

Pars des écrans existants: planning, portail client, liste des raisons de retard et modèles de notification. Claude Code classe les événements et signale ce qui peut sortir vers le client.

• 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 French 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

L’erreur la plus fréquente consiste à confondre redelivery Pub/Sub et nouvel avis client. Le transport peut réessayer; le client ne doit pas recevoir deux messages identiques.

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

Q. Exactly-once delivery suffit-il pour éviter les doublons ?\n\nR. Non. Le service de notification doit aussi enregistrer une clé d’idempotence avant tout envoi externe.

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

Pour la version française, j’ai gardé les écrans logistiques, les appels client, le DLQ et le lien vers la consultation comme axe principal. 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.