# 機能設計書：ジョブキュー

## 1. 機能概要

### 1.1 機能の目的
ジョブキュー機能は、非同期タスクの管理と実行を行うバックグラウンドジョブシステムである。メール送信、画像処理、データインポートなど、即座にレスポンスを返す必要がない処理をバックグラウンドで実行する。

### 1.2 機能の範囲
- ジョブのキューイング（追加）
- ジョブの実行（run）
- ジョブのキャンセル
- ワークフロー（複数タスクの連携）
- スケジュール実行
- リトライ処理とエラーハンドリング
- 同時実行制御（コンカレンシー）

### 1.3 関連画面
| 画面ID | 画面名 | 関連操作 |
|--------|--------|----------|
| ADM-030 | ジョブ一覧 | findJobs |
| ADM-031 | ジョブ詳細 | findJobByID |

---

## 2. 機能仕様

### 2.1 入力仕様

#### 2.1.1 タスク定義
```typescript
interface TaskConfig {
  slug: string;                    // タスク識別子
  handler: TaskHandler;            // タスク実行関数
  inputSchema?: JSONSchema;        // 入力スキーマ
  outputSchema?: JSONSchema;       // 出力スキーマ
  retries?: number | RetryConfig;  // リトライ設定
  queue?: string;                  // 使用キュー
  onFail?: OnFailHandler;          // 失敗時ハンドラ
  onSuccess?: OnSuccessHandler;    // 成功時ハンドラ
}
```

#### 2.1.2 ワークフロー定義
```typescript
interface WorkflowConfig {
  slug: string;                    // ワークフロー識別子
  handler: WorkflowHandler;        // ワークフロー実行関数
  inputSchema?: JSONSchema;        // 入力スキーマ
  queue?: string;                  // 使用キュー
  concurrency?: ConcurrencyConfig; // 同時実行制御
}
```

#### 2.1.3 Queue操作（ジョブ追加）
| パラメータ | 型 | 必須 | 説明 |
|-----------|-----|------|------|
| task | string | Yes* | タスクslug（taskまたはworkflowのいずれか） |
| workflow | string | Yes* | ワークフローslug |
| input | object | Yes | ジョブ入力データ |
| queue | string | No | キュー名（デフォルト: 'default'） |
| waitUntil | Date | No | 実行開始予定日時 |
| meta | object | No | メタデータ |
| overrideAccess | boolean | No | アクセス制御のオーバーライド |

#### 2.1.4 Run操作（ジョブ実行）
| パラメータ | 型 | 必須 | 説明 |
|-----------|-----|------|------|
| queue | string | No | 実行対象キュー（デフォルト: 'default'） |
| allQueues | boolean | No | 全キューから実行 |
| limit | number | No | 最大実行件数（デフォルト: 10） |
| sequential | boolean | No | 順次実行フラグ |
| processingOrder | Sort | No | 処理順序 |
| silent | boolean | No | ログ出力抑制 |
| where | Where | No | 追加フィルタ条件 |

### 2.2 出力仕様

#### 2.2.1 ジョブドキュメント構造
```typescript
interface Job {
  id: string | number;
  taskSlug?: string;           // タスクslug（タスクジョブの場合）
  workflowSlug?: string;       // ワークフローslug（ワークフローの場合）
  queue: string;               // キュー名
  input: object;               // 入力データ
  meta?: object;               // メタデータ
  processing: boolean;         // 処理中フラグ
  completedAt?: string;        // 完了日時
  hasError: boolean;           // エラー有無
  error?: object;              // エラー情報
  totalTried: number;          // 試行回数
  waitUntil?: string;          // 実行予定日時
  concurrencyKey?: string;     // 同時実行制御キー
  createdAt: string;
  updatedAt: string;
}
```

#### 2.2.2 Run操作の戻り値
```typescript
interface RunJobsResult {
  jobStatus?: Record<string, RunJobResult>;
  noJobsRemaining?: boolean;
  remainingJobsFromQueried: number;
}

interface RunJobResult {
  status: 'success' | 'error' | 'error-reached-max-retries';
}
```

### 2.3 処理フロー

```
[ジョブキューイングフロー（queue）]
1. アクセス制御チェック（overrideAccess=false時）
2. ワークフロー/タスク設定の取得
3. キュー名の決定（引数 > ワークフロー設定 > 'default'）
4. concurrencyKeyの計算（有効時）
5. supersedes=trueの場合、同一キーの未処理ジョブを削除
6. ジョブドキュメントの作成
7. 作成したジョブを返却
```

```
[ジョブ実行フロー（run）]
1. アクセス制御チェック
2. 実行可能ジョブの検索
   - completedAt: 未完了
   - hasError: false
   - processing: false
   - waitUntil: 現在時刻以前または未設定
3. 同時実行制御チェック（enableConcurrencyControl時）
4. ジョブをprocessing=trueに更新
5. 並列/順次でジョブを実行
6. 成功時: completedAt設定、deleteJobOnComplete時は削除
7. 失敗時: リトライ設定に基づき再スケジュール
8. 実行結果を返却
```

```
[ワークフロー実行フロー]
1. ワークフローハンドラの取得
2. tasksオブジェクト（各タスクの実行関数）の提供
3. ハンドラ内でtasksを使用してタスクを順次/並列実行
4. 全タスク完了またはエラー発生まで継続
5. ワークフロー完了またはリトライスケジュール
```

### 2.4 リトライ設定

```typescript
interface RetryConfig {
  attempts: number;           // 最大試行回数
  backoff?: {
    type: 'fixed' | 'exponential';
    delay: number;            // 基本遅延（ms）
  };
}
```

### 2.5 エラーハンドリング
| エラーコード | 説明 | HTTPステータス |
|-------------|------|---------------|
| Forbidden | アクセス権限がない | 403 |
| JobCancelledError | ジョブがキャンセルされた | - |

---

## 3. データ設計

### 3.1 ジョブコレクションスキーマ
```typescript
// payload-jobs コレクション
interface JobDocument {
  id: string | number;
  taskSlug?: string;
  workflowSlug?: string;
  queue: string;
  input: object;
  meta?: object;
  processing: boolean;
  completedAt?: string;
  hasError: boolean;
  error?: {
    message?: string;
    cancelled?: boolean;
  };
  totalTried: number;
  waitUntil?: string;
  concurrencyKey?: string;
  log?: TaskLog[];
  createdAt: string;
  updatedAt: string;
}
```

### 3.2 インデックス設計
| フィールド | 用途 |
|-----------|------|
| queue | キュー別検索 |
| processing | 処理中ジョブの検索 |
| completedAt | 完了ジョブの検索 |
| waitUntil | スケジュール実行の検索 |
| concurrencyKey | 同時実行制御 |

---

## 4. コードリーディングガイド

### 4.1 推奨読解順序

1. **ローカルAPIの理解**
   - `/packages/payload/src/queues/localAPI.ts`
   - **24-51行目**: handleSchedules - スケジュール処理
   - **52-248行目**: queue - ジョブ追加処理
   - **250-315行目**: run - ジョブ実行トリガー
   - **317-347行目**: runByID - ID指定実行
   - **349-415行目**: cancel - ジョブキャンセル

2. **ジョブ実行処理**
   - `/packages/payload/src/queues/operations/runJobs/index.ts`
   - **82-111行目**: 実行可能ジョブのクエリ条件構築
   - **157-194行目**: 同時実行制御（concurrencyKey）
   - **196-259行目**: ジョブの取得とprocessing更新
   - **262-297行目**: 同一concurrencyKeyのジョブ重複排除
   - **332-473行目**: runSingleJob - 単一ジョブの実行
   - **476-489行目**: 並列/順次実行の分岐

3. **型定義**
   - `/packages/payload/src/queues/config/types/taskTypes.ts` - タスク型
   - `/packages/payload/src/queues/config/types/workflowTypes.ts` - ワークフロー型

### 4.2 プログラム呼び出し階層図

```
payload.jobs.queue()
  |
  +-- accessFn() [overrideAccess=false時]
  |
  +-- concurrencyConfig.key() [enableConcurrencyControl時]
  |
  +-- [supersedes=true時]
  |     +-- deleteMany() [同一keyの未処理ジョブ削除]
  |
  +-- payload.create() or payload.db.create()
        |
        +-- [Jobドキュメント作成]
```

```
payload.jobs.run()
  |
  +-- accessFn() [overrideAccess=false時]
  |
  +-- [同時実行制御チェック]
  |     +-- payload.db.find() [処理中の同一keyジョブ検索]
  |
  +-- updateJobs() [processing=true]
  |
  +-- [並列 or 順次]
  |     +-- runSingleJob() [各ジョブ]
  |           |
  |           +-- workflowHandler() or runJSONJob()
  |
  +-- [deleteJobOnComplete時]
  |     +-- payload.delete() or deleteMany()
  |
  +-- [結果集計・返却]
```

### 4.3 データフロー図

```
[ジョブ追加]
       |
       v
+------------------+
| Access Control   | --> [Forbidden Error]
+------------------+
       |
       v
+------------------+
| Concurrency Key  |
| 計算             |
+------------------+
       |
       v
+------------------+
| Supersedes処理   |
| (同一key削除)    |
+------------------+
       |
       v
+------------------+
| Job作成          |
+------------------+
       |
       v
[Jobドキュメント]
```

```
[ジョブ実行]
       |
       v
+------------------+
| 実行可能ジョブ   |
| 検索             |
+------------------+
       |
       v
+------------------+
| Concurrency      |
| 制御             |
+------------------+
       |
       v
+------------------+
| processing=true  |
+------------------+
       |
       v
+------------------+
| ジョブ実行       |
+------------------+
       |
       +-- Success --> completedAt設定 --> [削除 or 保持]
       |
       +-- Error   --> リトライ判定 --> [再スケジュール or hasError=true]
```

### 4.4 関連ファイル一覧

| ファイルパス | 種別 | 役割 |
|-------------|------|------|
| `/packages/payload/src/queues/localAPI.ts` | API | ローカルAPI定義 |
| `/packages/payload/src/queues/operations/runJobs/index.ts` | 処理 | ジョブ実行処理 |
| `/packages/payload/src/queues/operations/runJobs/runJob/index.ts` | 処理 | 単一ジョブ実行 |
| `/packages/payload/src/queues/operations/handleSchedules/index.ts` | 処理 | スケジュール処理 |
| `/packages/payload/src/queues/config/types/taskTypes.ts` | 型定義 | タスク型 |
| `/packages/payload/src/queues/config/types/workflowTypes.ts` | 型定義 | ワークフロー型 |
| `/packages/payload/src/queues/errors/handleTaskError.ts` | エラー | タスクエラー処理 |
| `/packages/payload/src/queues/errors/calculateBackoffWaitUntil.ts` | ユーティリティ | バックオフ計算 |
| `/packages/payload/src/queues/utilities/updateJob.ts` | ユーティリティ | ジョブ更新処理 |

---

## 5. 設計上の考慮事項

### 5.1 パフォーマンス考慮
- limit指定による一度の実行件数制御
- 並列実行（デフォルト）による処理効率化
- sequential=trueで順次実行も可能
- processingOrder設定による優先度制御（FIFO/LIFO）

### 5.2 セキュリティ考慮
- queue/run/cancel各操作にアクセス制御
- overrideAccess=falseでアクセス制御を強制

### 5.3 拡張性考慮
- 複数キューによるワークロード分離
- ワークフローによる複雑なタスク連携
- カスタムリトライ戦略（exponential backoff）
- 同時実行制御（concurrencyKey）による重複防止

---

## 6. 変更履歴

| 日付 | バージョン | 変更内容 | 担当者 |
|------|-----------|----------|--------|
| 2026-03-01 | 1.0.0 | 初版作成 | AI |
