# バッチ設計書 3-queue:retry

## 概要

本ドキュメントは、Laravelフレームワークの失敗ジョブリトライコマンド `queue:retry` の設計仕様を記載したものです。本バッチは失敗したキュージョブを再度キューに投入する機能を提供します。

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

`queue:retry` コマンドは、失敗ジョブテーブル（failed_jobs）に記録されたジョブを取得し、元のキューに再投入するバッチ処理です。特定のジョブID、キュー名、ID範囲を指定してリトライ対象を選択できます。

**業務上の目的・背景**：キューシステムにおいてジョブの失敗は避けられない事象です。一時的なネットワーク障害、外部サービスの障害、リソース不足などで失敗したジョブを、障害復旧後に手動または自動で再実行する必要があります。本コマンドにより、失敗ジョブの管理と復旧を効率的に行うことができます。運用チームは失敗原因を調査した後、適切なタイミングでリトライを実行できます。

**バッチの実行タイミング**：障害復旧後や定期メンテナンス時に手動実行。または監視システムと連携した自動実行。

**主要な処理内容**：
1. 失敗ジョブテーブルから対象ジョブを検索
2. ジョブのペイロードを取得し、attemptsをリセット
3. retryUntilタイムスタンプを更新（該当する場合）
4. JobRetryRequestedイベントを発火
5. ジョブを元のキュー接続・キュー名に再投入
6. 失敗ジョブテーブルから該当レコードを削除

**前後の処理との関連**：`queue:failed` で失敗ジョブ一覧を確認後に実行。リトライ後は `queue:work` で処理されます。個別削除は `queue:forget`、全削除は `queue:flush` を使用。

**影響範囲**：failed_jobsテーブル（レコード削除）、jobsテーブルまたはキューストレージ（ジョブ追加）に影響を与えます。

## バッチ種別

データ復旧 / ジョブリトライ

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | 随時（手動実行） |
| 実行時刻 | 任意 |
| 実行曜日 | 該当なし |
| 実行日 | 該当なし |
| トリガー | 手動 / 監視システム連携 |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| 失敗ジョブの存在 | failed_jobsテーブルにリトライ対象のジョブが存在すること |
| キュー接続設定 | 元のキュー接続が利用可能であること |
| 暗号化設定 | ジョブペイロードが暗号化されている場合、Encrypterが設定されていること |

### 実行可否判定

- 指定されたジョブIDが存在しない場合はエラーメッセージを表示して継続
- "all" 指定時は全ての失敗ジョブを対象
- --queue オプション指定時は該当キューの失敗ジョブのみを対象

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| id | string/array | No | - | リトライするジョブID（複数指定可、"all"で全件） |
| --queue | string | No | - | 指定キューの全失敗ジョブをリトライ |
| --range | array | No | - | リトライするID範囲（例: 1-5） |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| failed_jobs テーブル | DB | 失敗ジョブの格納先 |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| 標準出力 | テキスト | リトライ処理の進捗・結果 |
| jobs テーブル/キュー | DB/Redis等 | 再投入されたジョブ |

### 出力ファイル仕様

該当なし（ファイル出力は行わない）

## 処理フロー

### 処理シーケンス

```
1. ジョブID取得
   └─ 引数、--queue、--range オプションからリトライ対象IDを決定
2. 各ジョブに対してループ処理
   └─ failed_jobsテーブルから該当ジョブを検索
3. ジョブ存在確認
   └─ 存在しない場合はエラーメッセージを表示して次へ
4. イベント発火
   └─ JobRetryRequestedイベントをディスパッチ
5. ジョブリトライ
   └─ attempts reset、retryUntil更新、キューに再投入
6. 失敗レコード削除
   └─ failed_jobsテーブルから該当レコードを削除
7. 結果表示
   └─ 処理完了メッセージまたは「No retryable jobs found」
```

### フローチャート

```mermaid
flowchart TD
    A[バッチ開始] --> B[リトライ対象ID取得]
    B --> C{ジョブあり?}
    C -->|No| D[No retryable jobs found]
    C -->|Yes| E[処理開始メッセージ]
    E --> F[次のジョブを取得]
    F --> G{ジョブ存在?}
    G -->|No| H[エラーメッセージ表示]
    H --> I{残りジョブあり?}
    G -->|Yes| J[JobRetryRequestedイベント発火]
    J --> K[ペイロードのattempts reset]
    K --> L[retryUntil更新]
    L --> M[キューに再投入]
    M --> N[failed_jobsから削除]
    N --> I
    I -->|Yes| F
    I -->|No| O[バッチ終了]
    D --> O
```

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

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

| 処理 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| ジョブ検索 | failed_jobs | SELECT | IDまたはキュー名でジョブを検索 |
| ジョブ削除 | failed_jobs | DELETE | リトライ成功後にレコード削除 |
| ジョブ投入 | jobs/キュー | INSERT/PUSH | キューにジョブを再投入 |

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

#### failed_jobs

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | id, connection, queue, payload | ID指定またはqueue指定 | ジョブ情報取得 |
| DELETE | - | id指定 | リトライ成功後 |

#### jobs（データベースキュー使用時）

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| INSERT | queue, payload, attempts, available_at, created_at | ペイロードを再構築して投入 | attempts=0にリセット |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | ジョブ未検出 | 指定IDのジョブが存在しない | IDを確認して再実行 |
| - | キュー未検出 | 指定キューにジョブが存在しない | キュー名を確認 |
| RuntimeException | ペイロード解析失敗 | 暗号化ジョブでEncrypterが未設定 | 暗号化設定を確認 |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | 本コマンド自体のリトライなし |
| リトライ間隔 | 該当なし |
| リトライ対象エラー | 該当なし |

### 障害時対応

1. 特定ジョブのリトライ失敗時は他のジョブの処理を継続
2. ペイロード解析失敗時はRuntimeExceptionをスロー
3. キュー接続失敗時は標準の例外処理に従う

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

| 項目 | 内容 |
|-----|------|
| トランザクション範囲 | ジョブ単位（各ジョブの削除と投入） |
| コミットタイミング | 各ジョブ処理完了時 |
| ロールバック条件 | ジョブ投入失敗時 |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | 数件〜数千件 |
| 目標処理時間 | ジョブ数に依存（1ジョブあたり数ミリ秒） |
| メモリ使用量上限 | 標準Artisanコマンドと同等 |

## 排他制御

- 同一ジョブに対する複数同時リトライは想定外
- ジョブ投入後に失敗レコードを削除するため、二重投入のリスクは低い
- Isolatableインターフェースは未実装

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| 開始ログ | 処理開始時 | Pushing failed queue jobs back onto the queue |
| 進捗ログ | 各ジョブ処理時 | ジョブID（タスク形式） |
| 終了ログ | 処理完了時 | なし（改行のみ） |
| エラーログ | ジョブ未検出時 | Unable to find failed job with ID [x] |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| 失敗ジョブ数 | 運用定義による | 監視システム |
| リトライ失敗 | エラーメッセージ発生時 | ログ監視 |

## 備考

- "all" 引数で全失敗ジョブをリトライ可能
- --range オプションで数値ID範囲を指定可能（例: --range=1-5）
- ペイロード内のattemptsは0にリセットされる
- retryUntilメソッドを持つジョブはタイムスタンプが更新される
- JobRetryRequestedイベントを購読してリトライ時の処理をカスタマイズ可能
