# バッチ設計書 13-queue:prune-failed

## 概要

本ドキュメントは、Laravelフレームワークの`queue:prune-failed`コマンドの設計仕様を定義するものです。このコマンドは、失敗ジョブテーブルから古いエントリを定期的に削除（プルーニング）するためのArtisanコマンドです。

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

**業務上の目的・背景**：キュー処理システムにおいて、失敗したジョブは`failed_jobs`テーブルに記録されます。これらのレコードは原因調査やリトライのために保持されますが、時間経過とともに不要になります。本コマンドは、指定した保持期間（デフォルト24時間）を超えた古い失敗ジョブを自動的に削除し、データベースの肥大化を防ぎます。`queue:flush`との違いは、デフォルトで期間ベースの削除を行う点であり、定期実行に適しています。

**バッチの実行タイミング**：日次（スケジューラーで定期実行）。Laravelのタスクスケジューラーに登録して自動実行することが推奨されます。

**主要な処理内容**：
1. `--hours`オプションから保持期間を取得（デフォルト24時間）
2. `queue.failer`がPrunableFailedJobProviderかどうかを確認
3. 指定期間より古い失敗ジョブを削除
4. 削除件数をコンソールに出力

**前後の処理との関連**：他のキュー関連コマンドとは独立して実行可能。定期的なメンテナンスタスクとしてスケジューラーに組み込まれることが想定されます。

**影響範囲**：`failed_jobs`テーブルから指定期間を超えた古いレコードが削除されます。

## バッチ種別

データクレンジング / 定期メンテナンス

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | 日次 |
| 実行時刻 | 任意（深夜帯推奨） |
| 実行曜日 | 毎日 |
| 実行日 | - |
| トリガー | cron/スケジューラー |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| PrunableFailedJobProvider | `queue.failer`がPrunableFailedJobProviderインターフェースを実装していること |

### 実行可否判定

`queue.failer`がPrunableFailedJobProviderでない場合はエラーメッセージを出力して終了コード1を返す。

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| --hours | integer | No | 24 | 失敗ジョブデータを保持する時間数 |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| failed_jobs | DB | 失敗したジョブの保存先テーブル |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| コンソール | テキスト | 削除件数メッセージ |

### 出力ファイル仕様

ファイル出力なし

## 処理フロー

### 処理シーケンス

```
1. queue.failerサービス取得
   └─ $this->laravel['queue.failer']
2. プロバイダー型チェック
   └─ PrunableFailedJobProviderかどうか確認
3. プルーニング実行
   └─ failer->prune(Carbon::now()->subHours(hours))
4. 結果出力
   └─ "{count} entries deleted."
```

### フローチャート

```mermaid
flowchart TD
    A[バッチ開始] --> B[queue.failer取得]
    B --> C{PrunableFailedJobProvider?}
    C -->|No| D[エラーメッセージ出力]
    D --> E[終了コード1で終了]
    C -->|Yes| F[保持期間を計算]
    F --> G[prune実行]
    G --> H[削除件数出力]
    H --> I[正常終了]
```

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

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

| 処理 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| 古い失敗ジョブ削除 | failed_jobs | DELETE | 指定時間より前のレコードを削除 |

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

#### failed_jobs

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| DELETE | - | WHERE failed_at < (現在時刻 - hours) | Carbonで計算 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| 1 | プロバイダー非対応 | queue.failerがPrunableFailedJobProviderでない | 対応プロバイダーを設定 |

### リトライ仕様

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

リトライ機構は実装されていない。

### 障害時対応

- プロバイダー非対応エラー: `config/queue.php`で対応するfailed job driverを設定
- データベース接続エラー: データベース設定を確認

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

| 項目 | 内容 |
|-----|------|
| トランザクション範囲 | プロバイダー実装による |
| コミットタイミング | プロバイダー実装による |
| ロールバック条件 | プロバイダー実装による |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | 可変（期間ベース） |
| 目標処理時間 | データ量に依存 |
| メモリ使用量上限 | 最小限 |

## 排他制御

排他制御なし。定期実行時は実行間隔を適切に設定すること。

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| 完了ログ | 削除完了時 | "{count} entries deleted." |
| エラーログ | プロバイダー非対応時 | "The [ProviderName] failed job storage driver does not support pruning." |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| 実行結果 | 終了コード1 | 運用担当 |

## 備考

- Laravel 12.x対応
- デフォルト保持期間は24時間
- `queue:flush --hours`との違い：本コマンドはデフォルトで24時間の保持期間が設定されており、定期実行向け
- スケジューラーでの使用例：`$schedule->command('queue:prune-failed')->daily();`
- DatabaseFailedJobProviderがデフォルトでPrunableFailedJobProviderを実装
