# バッチ設計書 10-queue:failed

## 概要

本ドキュメントは、Laravelフレームワークの失敗ジョブ一覧表示コマンド `queue:failed` の設計仕様を記載したものです。本バッチは失敗したキュージョブの一覧を表示する参照機能を提供します。

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

`queue:failed` コマンドは、failed_jobsテーブルに記録された失敗ジョブの一覧を、見やすいフォーマットでコンソールに表示するバッチ処理です。データの変更は行わず、参照のみの機能です。

**業務上の目的・背景**：キューシステムの運用において、失敗したジョブを把握することは障害対応の第一歩です。本コマンドにより、どのジョブがいつ、どのキューで失敗したかを即座に確認できます。運用チームは本コマンドの出力を基に、失敗原因を調査し、`queue:retry` でリトライするか `queue:forget` で削除するかを判断できます。日常的な監視や障害時の初動対応に活用されます。

**バッチの実行タイミング**：障害発生時、定期的な監視、リトライ実行前の確認時に手動実行。

**主要な処理内容**：
1. failed_jobsテーブルから全ての失敗ジョブを取得
2. 各ジョブのペイロードからジョブクラス名を抽出
3. ID、接続名、キュー名、クラス名、失敗日時を整形して表示
4. 失敗ジョブが存在しない場合は「No failed jobs found」を表示

**前後の処理との関連**：表示された失敗ジョブに対して、`queue:retry` でリトライ、`queue:forget` で個別削除、`queue:flush` で全削除が可能です。

**影響範囲**：failed_jobsテーブルへの参照のみ。データの変更は行いません。

## バッチ種別

参照 / 一覧表示

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | 随時（手動実行） |
| 実行時刻 | 任意 |
| 実行曜日 | 該当なし |
| 実行日 | 該当なし |
| トリガー | 手動 |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| 失敗ジョブテーブル | failed_jobsテーブルが存在すること |
| キューフェイラー設定 | queue.failedまたはqueue.failerが設定されていること |

### 実行可否判定

- 特別な実行条件なし
- 失敗ジョブが存在しない場合でもメッセージを表示して正常終了

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| なし | - | - | - | このコマンドはパラメータを受け取りません |

### 入力データソース

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

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| 標準出力 | テキスト（テーブル形式） | 失敗ジョブ一覧 |

### 出力ファイル仕様

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

### 表示カラム

| カラム | 説明 |
|-------|------|
| ID | 失敗ジョブID |
| Connection | キュー接続名 |
| Queue | キュー名 |
| Class | ジョブクラス名 |
| Failed At | 失敗日時 |

## 処理フロー

### 処理シーケンス

```
1. 失敗ジョブ取得
   └─ queue.failerのallメソッドで全失敗ジョブを取得
2. 存在チェック
   └─ 失敗ジョブが0件の場合は「No failed jobs found」を表示して終了
3. データ整形
   └─ 各ジョブのペイロードからクラス名を抽出
4. 一覧表示
   └─ twoColumnDetail形式で失敗ジョブを表示
```

### フローチャート

```mermaid
flowchart TD
    A[バッチ開始] --> B[queue.failer.all呼び出し]
    B --> C[失敗ジョブリスト取得]
    C --> D{失敗ジョブあり?}
    D -->|No| E[No failed jobs found表示]
    D -->|Yes| F[各ジョブをループ]
    F --> G[ペイロードからクラス名抽出]
    G --> H[表示データ整形]
    H --> I{残りジョブあり?}
    I -->|Yes| F
    I -->|No| J[twoColumnDetailで表示]
    E --> K[バッチ終了]
    J --> K
```

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

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

| 処理 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| 一覧取得 | failed_jobs | SELECT | 全失敗ジョブを取得 |

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

#### failed_jobs

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | id, connection, queue, payload, failed_at | 全件取得 | 参照のみ |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | テーブル未存在 | failed_jobsテーブルが存在しない | マイグレーション実行 |
| - | 接続エラー | データベース接続失敗 | 接続設定を確認 |

### リトライ仕様

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

### 障害時対応

1. データベース接続エラー時は接続設定を確認
2. テーブル未存在時はマイグレーションを実行

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

| 項目 | 内容 |
|-----|------|
| トランザクション範囲 | なし（参照のみ） |
| コミットタイミング | 該当なし |
| ロールバック条件 | 該当なし |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | 数件〜数千件 |
| 目標処理時間 | 数秒以内 |
| メモリ使用量上限 | 標準Artisanコマンドと同等 |

## 排他制御

- 排他制御不要（参照のみ）
- 複数プロセスから同時実行可能
- Isolatableインターフェースは未実装

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| 開始ログ | なし | なし |
| 進捗ログ | なし | なし |
| 結果ログ | 処理完了時 | 失敗ジョブ一覧（複数行） |
| 空結果ログ | 失敗ジョブなし時 | No failed jobs found. |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| 失敗ジョブ件数 | 運用定義による | 監視システム連携（本コマンド以外） |

## 備考

- 表示カラム: ID, Connection, Queue, Class, Failed At
- ペイロードからジョブクラス名を抽出（正規表現使用）
- シリアライズされたコマンドまたはjobキーからクラス名を取得
- twoColumnDetail形式で見やすく表示
- payloadとexceptionはプライバシー/長さの理由で表示対象外
- 大量の失敗ジョブがある場合はページングなしで全件表示
- 詳細な例外情報は直接データベースを参照する必要がある
- 関連コマンド: queue:retry, queue:forget, queue:flush
