# バッチ設計書 6-queue:clear

## 概要

本ドキュメントは、Laravelフレームワークのキュークリアコマンド `queue:clear` の設計仕様を記載したものです。本バッチは指定されたキューから全てのジョブを削除する機能を提供します。

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

`queue:clear` コマンドは、指定されたキュー接続とキュー名に対して、待機中の全てのジョブを一括削除するバッチ処理です。ClearableQueueインターフェースを実装したキュードライバでのみ使用可能です。

**業務上の目的・背景**：開発環境でのテストデータクリーンアップ、障害復旧時の不要ジョブの一括削除、キュー移行時のデータクリアなど、キュー内のジョブを一括で削除する必要がある場面で使用します。特に、バグのあるコードで大量のジョブが投入された場合や、テスト環境をリセットする場合に有用です。本番環境での使用は慎重に行う必要があります。

**バッチの実行タイミング**：障害対応時、環境リセット時、テストデータクリーンアップ時に手動実行。

**主要な処理内容**：
1. キュー接続とキュー名を取得
2. ClearableQueueインターフェースの実装を確認
3. clearメソッドを呼び出してジョブを削除
4. 削除件数を表示

**前後の処理との関連**：削除されたジョブは復旧不可能です。必要に応じて事前にバックアップを取得してください。失敗ジョブは `queue:flush` で別途削除します。

**影響範囲**：指定されたキューの全ジョブ（jobsテーブルまたはキューストレージ）が削除されます。

## バッチ種別

データ削除 / キュークリア

## 実行スケジュール

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

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| キュー接続設定 | 有効なキュー接続が設定されていること |
| ClearableQueue対応 | キュードライバがClearableQueueインターフェースを実装していること |
| 確認プロンプト | 本番環境では--forceオプションまたは確認プロンプトへの応答が必要 |

### 実行可否判定

- ClearableQueueを実装していないドライバはエラー終了
- ConfirmableTraitにより本番環境では確認プロンプトを表示
- --force オプションで確認をスキップ可能

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| connection | string | No | config値 | キュー接続名 |
| --queue | string | No | config値 | クリア対象のキュー名 |
| --force | bool | No | false | 確認プロンプトをスキップ |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| jobs テーブル/キュー | DB/Redis等 | 削除対象のジョブ |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| 標準出力 | テキスト | 削除件数メッセージ |

### 出力ファイル仕様

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

## 処理フロー

### 処理シーケンス

```
1. 確認プロンプト
   └─ 本番環境で--forceなしの場合、確認を要求
2. キュー接続取得
   └─ 引数またはconfig値からキュー接続を決定
3. キュー名取得
   └─ --queueオプションまたはconfig値からキュー名を決定
4. ClearableQueue確認
   └─ ドライバがClearableQueueを実装しているか確認
5. ジョブ削除
   └─ clearメソッドを呼び出し
6. 結果表示
   └─ "Cleared X job(s) from the [queue_name] queue"
```

### フローチャート

```mermaid
flowchart TD
    A[バッチ開始] --> B{確認プロンプト通過?}
    B -->|No| C[終了コード1で終了]
    B -->|Yes| D[キュー接続取得]
    D --> E[キュー名取得]
    E --> F[キューインスタンス取得]
    F --> G{ClearableQueue?}
    G -->|No| H[エラー: 非対応ドライバ]
    H --> C
    G -->|Yes| I[clearメソッド呼び出し]
    I --> J[削除件数取得]
    J --> K[結果メッセージ表示]
    K --> L[終了コード0で終了]
```

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

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

| 処理 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| ジョブ削除 | jobs | DELETE | 指定キューの全ジョブを削除 |

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

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

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| DELETE | - | queue = 指定キュー名 | 全件削除 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| 1 | 確認拒否 | 確認プロンプトでNoを選択 | --forceを使用 |
| 1 | 非対応ドライバ | ClearableQueue未実装 | 対応ドライバを使用 |

### リトライ仕様

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

### 障害時対応

1. 削除されたジョブは復旧不可
2. 事前バックアップを推奨
3. ClearableQueue非対応の場合は手動削除が必要

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

| 項目 | 内容 |
|-----|------|
| トランザクション範囲 | ドライバ依存 |
| コミットタイミング | ドライバ依存 |
| ロールバック条件 | ドライバ依存 |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | 任意（全件削除） |
| 目標処理時間 | ジョブ数に依存 |
| メモリ使用量上限 | 標準Artisanコマンドと同等 |

## 排他制御

- 削除中も他のワーカーがジョブを処理する可能性あり
- 完全なクリアが必要な場合はワーカーを停止してから実行
- Isolatableインターフェースは未実装

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| 開始ログ | なし | なし |
| 進捗ログ | なし | なし |
| 終了ログ | 処理完了時 | Cleared X job(s) from the [queue_name] queue |
| エラーログ | 非対応ドライバ時 | Clearing queues is not supported on [DriverName] |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| 削除件数 | 運用定義による | ログ監視 |
| 実行頻度 | 異常検知 | 監視システム |

## 備考

- ClearableQueueインターフェースを実装するドライバ: Database, Redis, SQS等
- 同期ドライバ（sync）は対応していない
- ConfirmableTraitを使用して本番環境での誤操作を防止
- ReflectionClassでドライバ名を取得してエラーメッセージに表示
- 削除されたジョブの復旧は不可能なため、使用時は注意が必要
- 失敗ジョブ（failed_jobs）は本コマンドでは削除されない
