物流延迟通知的 Pub/Sub 设计: Claude Code 检查流程

在物流公司，调度表里一个 ETA 改动，可能同时触发邮件、LINE、客户门户记录和客服跟进。如果 Pub/Sub consumer 在发送通知后、ack 之前停止，同一条消息可能再次到达。客户收到两条延迟通知，只能打电话确认哪个时间才是真的。本文把这个场景整理成 Claude Code 可检查的流程。

要点

物流场景的 Pub/Sub 设计，不应从 topic 名称开始，而要从客户通知开始。先决定哪种 ETA 变化需要外发，哪种只更新门户，哪种必须等调度或客服确认。Claude Code 负责起草表格，合同、赔偿、道歉文字和个人信息由人确认。

Workflow Before Pub/Sub Settings

在修改 subscription 之前，先画出从调度 CSV 到客户通知的路径。表里放 shipmentId、status、ETA、channel、template、retry count 和 reviewer。目标是减少重复通知、确认电话和客服检查时间。

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

从真实界面开始：调度看板、客户门户、延迟原因列表、通知模板。让 Claude Code 分类事件，并标出哪些可以发给客户。

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

最常见的错误，是把技术层的 redelivery 当成客户层的新通知。Pub/Sub 可以再次投递，但客户不应该收到同一条通知两次。

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 足够吗？\n\nA. 不够。邮件、LINE、门户记录之前，通知服务还要保存 idempotency key，并拦住重复 key。

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

中文版确认了物流语境、重复通知、DLQ 可见性、客户电话指标和咨询 CTA。 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.