# バッチ設計書 5-deleteScheduledPublishJobs

## 概要

本ドキュメントは、Payloadのコンテンツ管理における予約公開ジョブ削除処理「deleteScheduledPublishJobs」の設計仕様を定義する。この処理は、未実行のスケジュール公開ジョブを一括削除する責務を担う。

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

deleteScheduledPublishJobsは、特定のドキュメントに関連する未実行のschedulePublishジョブをジョブキューから削除するユーティリティ関数である。

**業務上の目的・背景**：コンテンツ管理において、予約公開が設定されたドキュメントが削除されたり、公開予定が変更されたりした場合、古い予約ジョブが残存すると不整合が発生する。deleteScheduledPublishJobsは、このような状況でジョブキューを整合性のある状態に保つために使用される。

**バッチの実行タイミング**：ドキュメントの削除時、または予約公開設定の変更時に呼び出される。これはバッチ処理というよりも、コンテンツ操作のフック内で同期的に実行されるユーティリティ関数である。

**主要な処理内容**：
1. 対象ドキュメントのID、コレクションslugを受け取る
2. payload-jobsコレクションから該当するジョブを検索
3. 検索条件：completedAt未設定、processing=false、input.doc.value=ID、input.doc.relationTo=slug、taskSlug=schedulePublish
4. 該当ジョブをdeleteManyで一括削除
5. エラー発生時はログ出力（処理は継続）

**前後の処理との関連**：ドキュメント削除フックやスケジュール変更処理から呼び出される。schedulePublishタスクが実行される前に、不要なジョブを削除する役割を担う。

**影響範囲**：payload-jobsコレクション内のschedulePublishタスクジョブ。

## バッチ種別

データクレンジング処理（ジョブキュークリーンアップ）

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | イベント駆動（随時） |
| 実行時刻 | ドキュメント操作時 |
| 実行曜日 | 該当なし |
| 実行日 | 該当なし |
| トリガー | ドキュメント削除/スケジュール変更 |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| ジョブキュー有効化 | Payload設定でjobs設定が有効であること |
| 対象ドキュメント存在 | 削除対象のドキュメントID・コレクションslugが有効であること |

### 実行可否判定

呼び出し元で判定。通常はドキュメント操作に伴って自動的に呼び出される。

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| id | number \| string | No | - | 対象ドキュメントID |
| slug | string | Yes | - | 対象コレクションslug |
| payload | Payload | Yes | - | Payloadインスタンス |
| req | PayloadRequest | No | - | リクエストオブジェクト |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| payload-jobs | DB | ジョブキューコレクション |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| payload-jobs | DB | 削除されたジョブレコード |

### 出力ファイル仕様

ファイル出力なし（データベース更新のみ）

## 処理フロー

### 処理シーケンス

```
1. 削除条件の構築
   └─ completedAt未設定、processing=false、input.doc.value=id、input.doc.relationTo=slug、taskSlug=schedulePublish
2. deleteManyの実行
   └─ 条件に一致するジョブを一括削除
3. エラーハンドリング
   └─ エラー発生時はログ出力、例外は再スローしない
```

### フローチャート

```mermaid
flowchart TD
    A[処理開始] --> B[削除条件構築]
    B --> C[deleteMany実行]
    C --> D{成功?}
    D -->|Yes| E[処理完了]
    D -->|No| F[エラーログ出力]
    F --> E
```

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

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

| 処理 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| ジョブ削除 | payload-jobs | DELETE | 条件一致ジョブの一括削除 |

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

#### payload-jobs

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| DELETE | completedAt | exists: false | 未完了のジョブのみ |
| DELETE | processing | equals: false | 処理中でないジョブのみ |
| DELETE | input.doc.value | equals: id | 対象ドキュメントID |
| DELETE | input.doc.relationTo | equals: slug | 対象コレクションslug |
| DELETE | taskSlug | equals: 'schedulePublish' | schedulePublishタスクのみ |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | DB接続エラー | データベース接続失敗 | ログ出力、処理は継続 |
| - | 権限エラー | 削除権限不足 | ログ出力、処理は継続 |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | なし |
| リトライ間隔 | - |
| リトライ対象エラー | - |

### 障害時対応

1. エラーログを確認
2. 残存ジョブを手動で確認・削除
3. 必要に応じてDB接続や権限を確認

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

| 項目 | 内容 |
|-----|------|
| トランザクション範囲 | deleteMany単位 |
| コミットタイミング | 削除完了時 |
| ロールバック条件 | deleteManyエラー時（ただし例外は再スローしない） |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | 1〜数件/呼び出し |
| 目標処理時間 | 数秒以内 |
| メモリ使用量上限 | 最小限 |

## 排他制御

- processing=falseのジョブのみを削除対象とすることで、実行中ジョブとの競合を回避
- 処理中（processing=true）のジョブは削除されないため、安全に呼び出し可能

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| エラーログ | 削除エラー発生時 | `There was an error deleting scheduled publish jobs from the queue for ${slug} document with ID ${id}.` |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| エラー発生頻度 | 設定による | 運用チーム |

## 備考

- この関数はエラーが発生しても例外を再スローしない（ログ出力のみ）
- これはドキュメント操作の一部として呼び出されるため、ジョブ削除失敗がメイン処理を中断しないようになっている
- payload.db.deleteManyを直接使用しており、フックは実行されない
- グローバルの予約公開ジョブには対応していない（input.docを条件としているため）
