定期タスク

機能

@nocobase/app-plugin-scheduler は、コードでスケジュールを宣言し、実行をホストの Jobs に任せ、起動のたびに記録します。同期、レポート、定期的な業務のチェックに使います。

スケジュールと対象はコードで宣言し、管理画面はアプリが所有します。任意の Cron やコードのエディターはありません。

シナリオと例

例：毎日の業務レポート

02:00 UTC にレポートを生成します。対象を実装してそのスケジュールを宣言し、管理者が起動の記録を確認して、必要に応じて無効にできるようにします。

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

Scheduler を使って、毎日 02:00 UTC に業務レポートを生成してください。先に
app.daily-report を実装して登録し、固定のスケジュールのキーを宣言して、ホストの Jobs を
組み込んでください。保護された一覧、起動の記録、有効・無効の操作を追加し、任意のコードの
エディターは追加しないでください。分離したデータと短い間隔で、タイムゾーン、業務の結果、
失敗、無効化をテストしてください。非同期の作業には状態の確認を追加してください。
不完全なマニフェストで finalize しないでください。

完了の条件スケジュールが宣言したタイムゾーンで実際のレポートを生成し、無効にすると新しい予定の作業が作られなくなること。

主な仕組みと実装

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

組み込みの領域	コードまたは設定の変更	画面と動作の変化
サーバーの Provider と対象	対象、検証、固定のキーを登録する	起動時の同期で業務のスケジュールが見つかる
Jobs の設定と終了	エグゼキューターを選び、処理が終わるまで依存関係を保つ	スケジュールと終了を調整する
スケジュールの管理画面	保護された操作で、スケジュールと起動の記録を読み取る	管理者が起動を確認し、今後の実行を制御する

組み込み

Server、Client、必要な CLI の入口を登録し、マイグレーションを適用して、JobExecutorServiceProvider を組み込みます。管理ページは、アプリが /api/scheduler の上に作ります。

スケジュールは jobs.default、または scheduler.jobs / SCHEDULER_JOBS で指定した設定を使います。メモリは 1 つのプロセス向けで、Redis は複数のインスタンスを調整します。選んだ設定の attempts は 1 のままにしてください。失敗からの復旧は業務の対象が担います。

スケジュールを宣言する

Provider の register() または boot() で、/server/tokens から schedulerServiceToken を解決します。

種類、検証、開始時の動作とともに registerTarget() を呼び出します。
アプリ全体で固定のキー、ルール、対象とともに defineSchedule() を呼び出します。
非同期の作業では状態の確認を提供し、返された対象のハンドルで最終的な結果を報告します。

app.daily-report を登録したら、毎日 02:00 UTC にスケジュールします。

scheduler.defineSchedule({
  key: 'daily-report',
  title: 'Daily report',
  schedule: { cron: '0 0 2 * * *', timezone: 'UTC' },
  target: { type: 'app.daily-report', config: {} },
});

scheduler は解決されたサービスです。対象は引き続きアプリが実装します。起動時の同期がこれらの宣言を読み取ります。実行時にスケジュールを作成する API ではありません。

確認と制御

操作	エンドポイント
一覧	`GET /api/scheduler/schedules`
詳細	`GET /api/scheduler/schedules/:id`
起動の記録	`GET /api/scheduler/schedules/:id/occurrences`
有効・無効	`POST /api/scheduler/schedules/:id/enable` または `/disable`

すべてに page:scheduler.schedules/access が必要です。対象の生の設定は返されず、任意のコードや Cron のエディターはありません。

CLI を登録していれば、pnpm nocobase scheduler sync で宣言を同期できます。--finalize は、ない定義を無効にするため、完全なデプロイのマニフェストがある場合にだけ使ってください。

AI 開発の制約と検証

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

宣言しても、その対象は実装されません。登録、検証、実際の業務の出力を確認してください。
複数のインスタンスには、適切な Jobs の調整を使ってください。メモリでのローカルの確認は、分散した環境での検収ではありません。
完了のコールバックが失われたあとの非同期の確認をテストし、有効なスケジュールを無効にしないよう、完全なマニフェストでだけ finalize してください。

検証

短いテスト用の間隔で、タイムゾーン、次の実行、起動の記録、業務の結果をテストしてから、無効化を検証します。非同期の対象は、完了の通知が失われても、確認によって復旧できるべきです。

終了時は、Scheduler の drain() が落ち着くまで依存関係を保ってください。外部の作業や人による作業がすべて終わるのを待つわけではありません。関連：バックグラウンドジョブ、スケジュール、プラグインを管理する。

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

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