Pub/Sub para avisos de retraso logístico: revisión con Claude Code

En una empresa logística, un cambio pequeño en la tabla de despacho puede activar correo, LINE, historial del portal y una llamada del equipo de atención. Si el consumidor de Pub/Sub cae después de enviar el aviso y antes del ack, el mensaje puede volver. El cliente recibe dos avisos de retraso y pregunta cuál ETA es válida. Este artículo propone un flujo de revisión con Claude Code para evitar esa escena.

Puntos clave

El diseño de Pub/Sub para logística empieza con la comunicación al cliente, no con el nombre del topic. Hay que decidir qué cambio de ETA envía aviso externo, qué cambio solo actualiza el portal y qué caso espera a una persona. Claude Code puede preparar la tabla de eventos; el equipo decide contratos, disculpas, compensación y privacidad.

Workflow Before Pub/Sub Settings

Antes de tocar subscriptions, dibuja el camino desde el CSV de despacho hasta el aviso al cliente. La tabla debe tener shipmentId, estado, ETA, canal, plantilla, retry count y revisor. La meta es reducir avisos duplicados, llamadas de aclaración y tiempo de revisión.

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

Empieza con las pantallas reales: tablero de despacho, portal del cliente, lista de motivos de retraso y plantillas. Pide a Claude Code clasificar cada evento y marcar si puede salir de la empresa.

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

El fallo principal es confundir reintento técnico con aviso al cliente. Pub/Sub puede entregar otra vez; eso no significa que el correo deba salir otra vez.

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

P. ¿Exactly-once delivery elimina la idempotencia?\n\nR. No. El servicio de notificaciones aún debe guardar una clave de idempotencia antes de enviar correo, LINE o historial del portal.

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

En la versión en español comprobé que el artículo mantiene el contexto de logística, métricas de llamadas, DLQ y la ruta hacia consultoría. 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.