# バッチ設計書 3-autoRun

## 概要

本ドキュメントは、Payloadのジョブキューシステムにおける自動実行設定「autoRun」の設計仕様を定義する。この設定は、cron設定に従いキュー内のジョブを定期的に自動実行する仕組みを提供する。

### 本バッチの処理概要

autoRunは、Payloadのジョブキューシステムにおいて、cronスケジュールに基づいてジョブの自動実行を行う設定機能である。内部的にはcronerライブラリを使用してcronジョブを登録し、指定された間隔でrunJobsを呼び出す。

**業務上の目的・背景**：ジョブキューシステムでは、キューに登録されたジョブを定期的に消化する仕組みが必要である。autoRunは、開発者がcron設定を指定するだけで自動的にジョブを実行する仕組みを提供し、運用の手間を削減する。ただし、サーバーレス環境では制約があるため、従来型のサーバー環境での使用が推奨される。

**バッチの実行タイミング**：cron設定に従って定期実行（デフォルト：毎分）。Payload起動時にcronジョブが登録され、以降はスケジュールに従って自動実行される。

**主要な処理内容**：
1. Payload起動時にcronジョブの登録
2. shouldAutoRun関数による実行可否判定（設定されている場合）
3. disableScheduling=falseの場合、handleSchedulesの呼び出し
4. runJobsの呼び出しによるジョブ実行
5. 実行結果のログ出力

**前後の処理との関連**：autoRunはhandleSchedulesとrunJobsを統合する上位レベルの機能である。handleSchedulesでジョブをキューイングし、runJobsで実際に実行する。

**影響範囲**：payload-jobsコレクション内のジョブ、およびジョブが操作対象とする全データ。

## バッチ種別

自動実行制御（cronベースのジョブ実行トリガー）

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | cron設定による（デフォルト：毎分） |
| 実行時刻 | cron式に依存（デフォルト: `* * * * *`） |
| 実行曜日 | cron式に依存 |
| 実行日 | cron式に依存 |
| トリガー | cron（cronerライブラリ） |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| autoRun設定 | Payload設定でjobs.autoRunが定義されていること |
| 非サーバーレス環境 | Vercelクローン等のサーバーレス環境では非推奨 |
| shouldAutoRun | 設定されている場合、trueを返すこと |

### 実行可否判定

- Payload起動時にautoRun設定が存在すること
- shouldAutoRun関数が定義されている場合、実行時にtrueを返すこと
- サーバーレス環境では、コールドスタートの問題によりcronジョブが正常に動作しない可能性がある

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| allQueues | boolean | No | false | trueの場合、全キューのジョブを実行 |
| cron | string | No | `* * * * *` | cron式（毎分） |
| disableScheduling | boolean | No | false | trueの場合、handleSchedulesをスキップ |
| limit | number | No | 10 | 1回の実行で処理するジョブの最大数 |
| queue | string | No | 'default' | 対象キュー名 |
| silent | RunJobsSilent | No | false | ログ出力の抑制 |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| jobsConfig.autoRun | 設定 | autoRun設定配列またはファクトリ関数 |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| payload-jobs | DB | 更新されたジョブレコード（runJobs経由） |
| コンソール | ログ | 実行結果ログ（silent=false時） |

### 出力ファイル仕様

ファイル出力なし

## 処理フロー

### 処理シーケンス

```
1. Payload起動時のautoRun設定読み込み
   └─ jobsConfig.autoRunから設定を取得（配列または関数）
2. cronジョブの登録
   └─ cronerライブラリで各設定のcronジョブを登録
3. cron実行時の処理
   └─ shouldAutoRunチェック（設定時）
4. handleSchedulesの呼び出し（disableScheduling=false時）
   └─ スケジュールされたジョブをキューに追加
5. runJobsの呼び出し
   └─ キュー内のジョブを実行
6. 次回実行まで待機
```

### フローチャート

```mermaid
flowchart TD
    A[Payload起動] --> B[autoRun設定読み込み]
    B --> C{autoRun設定存在?}
    C -->|No| D[終了]
    C -->|Yes| E[cronジョブ登録]
    E --> F[cron時刻到来]
    F --> G{shouldAutoRun?}
    G -->|No| F
    G -->|Yes| H{disableScheduling?}
    H -->|No| I[handleSchedules呼び出し]
    H -->|Yes| J[runJobs呼び出し]
    I --> J
    J --> K[結果ログ出力]
    K --> F
```

## データベース操作仕様

### 操作別データベース影響一覧

| 処理 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| スケジュール処理 | payload-jobs | INSERT | handleSchedules経由でジョブ追加 |
| ジョブ実行 | payload-jobs | SELECT/UPDATE/DELETE | runJobs経由でジョブ処理 |

### テーブル別操作詳細

autoRun自体はデータベースを直接操作しない。handleSchedulesとrunJobsの設計書を参照。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | cron登録エラー | 無効なcron式 | cron式の修正 |
| - | shouldAutoRunエラー | shouldAutoRun関数内でエラー | 関数実装の修正 |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | なし（autoRun自体のリトライはなし） |
| リトライ間隔 | - |
| リトライ対象エラー | - |

### 障害時対応

1. cron式の設定を確認
2. shouldAutoRun関数のログを確認
3. handleSchedules/runJobsのエラーログを確認

## トランザクション仕様

| 項目 | 内容 |
|-----|------|
| トランザクション範囲 | handleSchedules/runJobsに委譲 |
| コミットタイミング | handleSchedules/runJobsに委譲 |
| ロールバック条件 | handleSchedules/runJobsに委譲 |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | limit設定による（デフォルト10件/実行） |
| 目標処理時間 | ジョブ内容に依存 |
| メモリ使用量上限 | 制限なし |

## 排他制御

- 同一cron設定内での重複実行はcronerライブラリにより防止
- ジョブレベルの排他制御はrunJobsに委譲

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| 実行ログ | runJobs実行時 | silent=false時のみ出力 |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| cron実行失敗 | 設定による | 運用チーム |
| ジョブ滞留 | 設定による | 運用チーム |

## 備考

- **サーバーレス環境非推奨**：Vercel、AWS Lambda等のサーバーレス環境では、コールドスタートの問題によりcronジョブが正常に動作しない可能性がある。代わりにVercel CronやAWS EventBridge経由でrunJobsエンドポイントを呼び出すことを推奨。
- autoRun設定は配列または関数（Payloadインスタンスを受け取る）として定義可能
- 複数のautoRun設定を定義して、異なるキューや異なるスケジュールでジョブを実行可能
- cron式の形式：`秒 分 時 日 月 曜日`（秒はオプション）
