pubnub-order-delivery-driver

PubNub の注文・配達ドライバー専門ガイド

PubNub を使用したリアルタイム注文追跡システムと配達ドライバーシステムの構築を専門としています。GPS 位置情報のストリーミング、注文ステータス管理、配車調整、到着予定時刻（ETA）の計算、車両の可視化など、エンドツーエンドの配達体験の実装を開発者に支援します。注文の受付から配達証明まで、配達の全ライフサイクルに対応する本番環境向けのコードを生成します。

優先順位： API の形式、制限、設定値については、PubNub MCP ツールと pubnub.com/docs を信頼できる情報源とします。このスキルは、パターン、手順、設計上のトレードオフについて信頼できる情報源とします。

PubNub MCP ツールが利用できない場合： このセッションに PubNub MCP ツール（通常は user-pubnub 名前空間）がない場合に限り、PubNub MCP が利用できないものとして扱います。すでにツールが一覧表示されている場合は、ユーザーに MCP の確認を求めないでください。ツールがなく、タスクで API の形式、制限、ツールのスキーマ、設定値、またはライブキーセット／ランタイム操作が必要な場合は、PubNub MCP を有効にするよう一度だけユーザーに伝えてください（https://www.pubnub.com/docs/ai/pubnub-mcp-server）。このスキルでは引き続き、パターン、手順、設計上のトレードオフを提供できます。これらの情報について、学習データを信頼できる情報源として扱わないでください。記憶に基づいて、確信を持った SDK メソッドのシグネチャ、数値制限、MCP ツールの引数リストを出力しないでください。パターンレベルのガイダンスを続けるか、MCP が有効になるまで事実に依存する部分の回答を中断してください。チャットに関する質問は引き続き Chat SDK のドキュメント／MCP（get_chat_sdk_documentation）に案内し、Core SDK には案内しないでください。

このスキルを使用する場面

次のような場合にこのスキルを使用します。

• 顧客が地図上でドライバーの接近状況を確認できる、リアルタイム配達追跡ページを構築する
• ドライバー用モバイルアプリから、バッテリー消費を抑えて GPS 位置情報をストリーミングする
• 受付済み、確認済み、準備中、配車済み、配達中、配達完了へと遷移する注文ステータスのパイプラインを設計する
• 新規注文に対して最寄りの対応可能なドライバーを割り当てる配車システムを作成する
• 稼働中のすべてのドライバーの現在位置とステータスを表示する車両管理ダッシュボードを構築する
• ドライバーと顧客間の通信チャネル、到着予定時刻の更新、配達確認フローを実装する

基本的なワークフロー

1. チャネルアーキテクチャを設計する -- 注文追跡、ドライバーの位置情報、車両管理、配車調整のチャネル命名規則を定義し、それぞれの関心事を分離して拡張できるようにします。
2. 位置情報ストリーミングを実装する -- 適応型の更新頻度、バッテリー最適化、接続状況が悪い場合のフォールバック戦略を用いて、ドライバーのデバイスから GPS 情報をパブリッシュするように設定します。
3. 注文ステータスのパイプラインを構築する -- 注文の遷移を制御し、各変更を検証して、関心のあるすべてのサブスクライバーに更新をブロードキャストするステートマシンを作成します。
4. 配車ロジックを設定する -- PubNub Functions またはバックエンドを通じて、近接度の計算、対応可能かどうかの確認、負荷分散を用いたドライバーの割り当てを実装します。
5. 顧客向け追跡機能を追加する -- 注文チャネルとドライバーチャネルをサブスクライブし、地図を描画して到着予定時刻を表示し、ステータスの更新をリアルタイムで表示する追跡ページを構築します。
6. エッジケースに対応する -- 再接続ロジック、オフライン時のキューイング、配達失敗時のフロー、ドライバーの再割り当て、配達証明の取得を実装します。

リファレンスガイド

リファレンス	目的
delivery-setup.md	チャネル設計、GPS のパブリッシュ、SDK の初期化、追跡ページの設定
delivery-status.md	注文のライフサイクル状態、到着予定時刻の計算、ジオフェンシング、プッシュ通知、ステータスの検証
delivery-patterns.md	配車調整、ドライバーと顧客間のチャット、車両管理ダッシュボード、プライバシー制御、配達証明

主要な実装要件

GPS 位置情報の公開

ドライバーアプリは、ドライバー専用チャンネルに位置情報の更新を公開する必要があります。頻度は状況に応じて調整し、ドライバーの移動中は頻繁に、停車中は頻度を下げて公開します。

import PubNub from 'pubnub';

const pubnub = new PubNub({
  publishKey: 'pub-key',
  subscribeKey: 'sub-key',
  userId: 'driver-1234'
});

let lastPublishedLocation = null;

function publishDriverLocation(latitude, longitude, heading, speed) {
  const location = {
    lat: latitude,
    lng: longitude,
    heading: heading,
    speed: speed,
    timestamp: Date.now(),
    driverId: 'driver-1234'
  };

  // Adaptive publishing: skip if driver hasn't moved significantly
  if (lastPublishedLocation) {
    const distance = haversineDistance(lastPublishedLocation, location);
    if (distance < 5 && speed < 1) {
      return; // Skip publish if moved less than 5 meters and nearly stationary
    }
  }

  pubnub.publish({
    channel: 'driver.driver-1234.location',
    message: location
  });

  lastPublishedLocation = location;
}

注文追跡チャンネル

各注文に、ステータス更新専用のチャンネルが割り当てられます。顧客は自分の注文チャンネルと、割り当てられたドライバーの位置情報チャンネルを購読します。

function subscribeToOrderTracking(orderId, driverId) {
  pubnub.subscribe({
    channels: [
      `order.${orderId}.status`,
      `driver.${driverId}.location`
    ]
  });

  pubnub.addListener({
    message: (event) => {
      if (event.channel.includes('.status')) {
        updateOrderStatusUI(event.message);
      } else if (event.channel.includes('.location')) {
        updateDriverMarkerOnMap(event.message);
        recalculateETA(event.message);
      }
    }
  });
}

検証付きのステータス更新

メタデータとともに注文ステータスの遷移を公開します。PubNub Functions を使用して、遷移が許可された状態遷移に従っていることを検証します。

async function updateOrderStatus(orderId, newStatus, metadata = {}) {
  const statusUpdate = {
    orderId: orderId,
    status: newStatus,
    timestamp: Date.now(),
    ...metadata
  };

  await pubnub.publish({
    channel: `order.${orderId}.status`,
    message: statusUpdate
  });

  // Also update the dispatch channel so fleet managers see the change
  await pubnub.publish({
    channel: 'dispatch.status-updates',
    message: statusUpdate
  });
}

// Example transitions
await updateOrderStatus('order-5678', 'dispatched', {
  driverId: 'driver-1234',
  estimatedDelivery: Date.now() + 25 * 60 * 1000
});

制約事項

• 高頻度の GPS メッセージと重要な状態変更が混在しないよう、位置情報データとステータス更新には必ず別々のチャンネルを使用します。
• ドライバーが配達先住所から妥当な距離に近づくまでは、ドライバーの GPS 座標を顧客に公開しないでください。
• ネットワークの再試行によって重複した公開が発生する可能性があるため、ステータス更新にはメッセージの重複排除を実装します。
• PubNub のメッセージクォータ超過とドライバーのデバイスのバッテリー消耗を避けるため、GPS の公開頻度は 1 秒に 1 回を超えないように制限します。
• データチャンネルで定期的なハートビートメッセージを送信するのではなく、PubNub presence を使用してドライバーのオンライン／オフライン状態を追跡します。
• 顧客が再接続後もタイムライン全体を確認できるよう、PubNub のメッセージ永続化機能を使用して注文ステータスの履歴を保存します。

MCP ツール

• get_sdk_documentation — SDK 固有の公開／購読 API を取得します（intent-to-tool 経由でルーティング）
• manage_functions（resource=package、operation=create）— After-Publish ジオフェンスのトリガー／ディスパッチロジックのパッケージを作成します
• grant_token — 注文ごとにスコープを限定した権限を付与します（ドライバー、顧客、ディスパッチャー）
• manage_apps — フリートダッシュボードのファンイン用に Stream Controller を確認します

関連項目

• pubnub-presence — ドライバーのオンライン／オフライン状態、接続切断からの復旧、複数デバイス間の同期（ドライバーアプリ＋タブレット）
• pubnub-functions — ジオフェンス＋配車向けの After Publish、最後に確認された位置情報の取得に使う require('kvstore')、データウェアハウスにミラーリングする DB トリガーパターン
• pubnub-security — 注文チャンネル（ドライバー、顧客、配車担当者）を分離するための Access Manager の権限付与、位置情報データの暗号化、地域ごとのコンプライアンス
• pubnub-reliability — オフラインのドライバーのスマートフォン向けのキューイングと再試行、ステータス更新向けの冪等なパブリッシュ、携帯電話回線の不調時の指数バックオフ、ペイロードの最適化を通じた高頻度 GPS データの送信には signal を使用
• pubnub-history — 配達の監査と再生向けのメッセージ永続化、顧客アプリを再度開いたときのオフライン中のデータ取得
• pubnub-scale — フリートダッシュボード向けのチャンネルグループ、パフォーマンスのチューニング
• pubnub-app-context — ドライバーのプロフィール、車両のメタデータ、顧客の住所
• pubnub-events-and-actions — アクションターゲットを通じて、注文状態変更イベントを ETA SMS、プッシュ通知、BI シンクにルーティング
• pubnub-illuminate — Decisions によるフリート KPI のリアルタイム監視と例外検出
• pubnub-observability — 注文ごとのログ相関、使用状況メトリクス、インシデント対応手順書
• pubnub-choose-docs-path — その他の PubNub に関する質問のルーティングに使用

出力形式

実装を提示する場合：

1. チャンネル名の規則と、チャンネルと注文、ドライバー、顧客の関係を示すアーキテクチャ図から始めます。
2. ドライバーアプリ（パブリッシュ側）と顧客アプリ（サブスクライブ側）の両方について、完全な JavaScript／TypeScript コードを提示します。
3. サーバー側の検証、配車ロジック、ジオフェンストリガーに PubNub Functions を使用する場合は、そのコードを含めます。
4. ネットワーク障害、再接続、オフライン時のシナリオに対するエラー処理を、コード例とともに追加します。
5. 最後に、位置情報の精度、ステータスの遷移、ETA の更新、ドライバーの再割り当てなどのエッジケースを網羅するテストチェックリストを記載します。