通知

機能

@nocobase/app-plugin-notification は、メッセージを検証、保存してキューに入れ、冪等性と上限のある再試行を扱い、配信の結果を記録します。配信の実装は、通知チャネル、アプリ内通知、Web プッシュ が提供します。

ランタイムが配信を取りまとめ、受信者、業務のきっかけ、送信の手段は、アプリとチャネルのプラグインが提供します。

シナリオと例

例：2 つのチャネルで通知する

注文の操作が成功したら、受信トレイとメールのメッセージを用意します。受信トレイの受信者はユーザー ID で、メールの受信者はメールアドレスで、業務コードが解決します。idempotencyKey には、固定の業務上のイベントの識別子を使います。

受信者ごとに配信は独立しています。1 つが失敗しても、すべてが失敗したわけではなく、再試行では元のチャネルとプロバイダーが保たれます。プロバイダーが受け付けたことは、受信や閲覧の証明ではありません。

開発用のプロンプト（アプリのディレクトリで作業するコーディングエージェント向け）：

Notifications を使って、注文の承認が成功したあとに受信トレイとメールのメッセージを送ってください。
完全なメッセージで、設定済みの名前付きのチャネルを使い、ユーザー ID とメールアドレスは別々に
解決してください。業務上のイベントの冪等性キーを使い、受信者ごとの結果を保持し、保護された
ログを組み込んでください。重複したイベント、部分的な失敗、ログへのアクセスの拒否をテストしてください。
キューに受け付けられたことを受信として表示しないでください。

完了の条件配信がイベントまで追跡でき、失敗がチャネルと受信者ごとに特定され、重複した送信で意図しない通知の繰り返しが起きないこと。

主な仕組みと実装

以下は、この例での組み込みの領域と、想定される画面の変化です。開発作業を記述したもので、実際のファイル構成はアプリに合わせてください。

組み込み

Server プラグインと必要なチャネルのプラグインを登録し、マイグレーションとシードを適用して、ホストの Jobs のエグゼキューターが動いていることを確認します。Client プラグインはログの組み込みを提供しますが、ページを自動では登録しません。

notification.channels の各エントリーには名前と type があります。たとえば system-email は smtp のチャネルの名前にできます。既定のテンプレートは、server/config/notification.ts の defineMailChannelsConfig でこれを組み立てています。

メッセージを送る

信頼できる業務コードで、/server から notificationServiceToken を解決します。アプリ内のプラグインを登録し、inbox: { type: 'in-app' } を設定した場合：

await notification.send({
  idempotencyKey: 'order:123:approved',
  source: { type: 'order', referenceId: '123' },
  messages: {
    inbox: {
      to: 'user-123',
      title: 'Order approved',
      body: 'The order is ready for processing.',
      target: { type: 'route', path: '/orders/123' },
    },
  },
});

ここでの notification は解決されたサービスです。実際の業務の ID を使ってください。messages の各キーは設定済みのチャネルの名前で、それぞれに完全なメッセージを持ちます。汎用のメッセージの自動変換はありません。

AI 開発の制約と検証

プラグイン固有の開発の制約

• 業務の成功と配信は別々に扱ってください。再試行で新しい冪等性キーを生成するのではなく、イベントの識別子を固定に保ってください。
• 各チャネルのペイロードを検証してください。ユーザー ID はメールアドレスではありません。
• 部分的な失敗とログへのアクセスをテストしてください。一時的な認証情報の配信には、永続的な再試行や冪等性の保証はありません。

ログと機密のメッセージ

/api/notifications/logs には page:notification.logs/access が必要です。保護されたログのページを作り、送信が返した通知の識別子を調べます。保護のない汎用の送信のエンドポイントを公開しないでください。

一度きりの認証情報には sendTransient({ channel, message }) を使います。通知のスナップショット、Jobs、永続的な冪等性、再試行なしに、配信を一度だけ試みます。タイムアウトは、送信の結果が不明であることを意味する場合があり、復旧は業務の流れが担います。

受信者ごとの結果、重複したイベント、チャネルの失敗、ログへのアクセスを検証します。関連：通知チャネル、アプリ内通知、Web プッシュ。

これらはあなたの組み込みの検収の要件であり、実機での検証が完了したことを示すものではありません。実際の変更、実行したチェック、未検証の項目をエージェントに報告させてください。プロジェクトのガイダンス、スキル、共通のチェックについては アプリの開発を続ける と テスト を参照してください。

出典：公開のプラグインの入口と実装。