メール

メール

機能

@nocobase/app-plugin-mail は、ユーザーが接続したメールボックスを管理します。認可、同期、閲覧、作成、送信、下書き、添付ファイル、配信の履歴です。システムのメールには通知チャネルを使い、個人のメールボックスを読んだり、その人の接続済みのアカウントで送信したりするには Mail を使います。

個人のアカウントとワークスペースのページはアプリがマウントします。システムの通知メールは通知チャネルを使います。

シナリオと例

例：顧客とのやり取り

アカウントを接続し、最初の同期の開始日を選びます。
関係するメッセージが同期されるのを待ちます。
MailClient.listMessages({ participant: 'alice@example.com' }) を使います。ドメインを完全一致させるには participant: '@example.com' を使います。
結果をレンダリングし、作成時にはユーザーが送信できる差出人を選べるようにします。

participant は、実際の From、To、Cc のアドレスに一致します。ドメインの一致にサブドメインは含まれません。メールボックスへのアクセスを広げたり、同期していないリモートの履歴を検索したりはしません。あいまいなキーワード検索には、別に q を使います。

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

Mail を使って、現在のユーザーの顧客とのやり取りを表示してください。Mail の設定を組み込み、
個人のアカウントの接続とワークスペースのページを、既存のアクセスのチェックとともに組み込んでください。
同期済みのメッセージを顧客の参加者のアドレスの完全一致で照会し、読み込みと失敗を扱ってください。
送信できる差出人を選び、業務レコードを正確な送信の ID と結び付けてください。テスト用の
メールボックスで、同期、送信、受信、メールボックスの分離を検証してください。結果が不明な送信を
やみくもに再送しないでください。

完了の条件顧客の詳細に、そのユーザーの同期済みのやり取りが表示され、送信が正確にレコードと結び付き、ほかのメールボックスにはアクセスできないままであること。

主な仕組みと実装

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

組み込みの領域	コードまたは設定の変更	画面と動作の変化
Mail の設定とアプリの組み立て	mailConfig と名前付きのプロバイダーを組み込む	認可と同期が設定したサービスを使う
クライアントのルートとメールボックスのページ	MailAccountsPage と MailWorkspacePage を組み立てる	ユーザーが個人のメールボックスを接続し、ワークスペースを開く
顧客の詳細と送信のコールバック	participant で照会し、送信の ID を保持する	認可された同期済みのメールを表示し、送信の結果を追跡する

設定

両方のランタイムを登録し、マイグレーションを適用します。Mail の設定は明示的に組み込みます。登録しても、アプリの設定の組み立ては変わりません。

// server/config/mail.ts
import { mailConfig } from '@nocobase/app-plugin-mail/server';
export default mailConfig;

このファクトリーを defaultAppConfigs() の mail に追加し、その設定の型を更新します。名前付きのインスタンスは mail.providers で設定します。組み込みの Gmail、Microsoft 365、IMAP/SMTP の実装にも、外部のサービスの設定が必要です。

認証情報はサーバーの非公開の設定に置きます。プロバイダーの OAuth のコールバックを設定し、mail.oauthReturnUrl をアプリの個人のアカウントのページに設定します。既定はアプリのルートです。

画面を組み立てる

Mail のページは自動では登録されません。/client は次を提供します。

個人の接続のための MailAccountsPage。
アカウントの管理を指す accountsHref を持つ MailWorkspacePage。
/api/mail にアクセスするための MailClient と mailClientToken。
作成、一覧、会話、ラベル、署名のための /client/components。

個人のアカウントのページには、認証と page:mail.workspace/access が必要です。管理者の概要は、個人のアカウントの接続の代わりにはなりません。

AI 開発の制約と検証

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

管理者の概要は個人の認可の代わりにはなりません。メールボックスへのアクセスのチェックを保ってください。participant でアクセスは広がりません。
アドレスとドメインの完全一致は、あいまいな q と分けてください。照会が同期していないリモートのメールまで調べると思わせないでください。
OAuth の戻り先のパス、同期の範囲、送信の状態を確認してください。結果が不明な送信を再試行する前に、その送信を調べてください。

検証と拡張

コールバック、同期、閲覧、送信、下書き、添付ファイルを検証します。送信、失敗、不明な結果を区別してください。業務レコードは、最新の履歴の行ではなく、作成画面の正確な送信の ID と結び付けます。

サーバーの組み込みには mailServiceToken を使い、独自のプロバイダーは mailProviderRegistryToken で登録します。プロバイダーが実際に対応している機能をレンダリングしてください。既存のデータがある場合のアップグレードでは、マイグレーションの要件を確認してください。参加者のインデックスや IMAP の場所のマイグレーションには、オフラインの保守の時間枠が必要になることがあります。

関連：通知チャネル、認証、プラグインを管理する。

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

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

機能