# バッチ設計書 25-cache:clear

## 概要

本ドキュメントは、Laravelフレームワークのアプリケーションキャッシュクリアコマンド `cache:clear` の設計仕様を定義します。

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

`cache:clear` コマンドは、アプリケーションのキャッシュストアをフラッシュ（全消去）するバッチ処理です。Redis、Memcached、ファイルベースなど、様々なキャッシュドライバに対応し、蓄積されたキャッシュデータを一括で削除します。また、リアルタイムファサードのキャッシュファイルも同時にクリアします。

**業務上の目的・背景**：アプリケーション運用において、キャッシュデータが古くなったり、設定変更後に古いキャッシュが残存することで、予期しない動作が発生することがあります。デプロイ後の環境更新、設定変更の反映、トラブルシューティングなど、様々な場面でキャッシュをクリアする必要があります。本バッチは、これらの運用作業を安全かつ効率的に実行します。

**バッチの実行タイミング**：主に以下のタイミングで実行されます。
- アプリケーションデプロイ後
- 設定ファイル変更後
- キャッシュ関連の問題発生時のトラブルシューティング
- 定期的なキャッシュメンテナンス

**主要な処理内容**：
1. `cache:clearing` イベントを発火（クリア前通知）
2. 指定されたキャッシュストアの `flush()` を実行
3. リアルタイムファサードのキャッシュファイルを削除
4. `cache:cleared` イベントを発火（クリア後通知）

**前後の処理との関連**：`optimize:clear` コマンドの一部として実行されることがあります。デプロイパイプラインでは、`config:clear`、`route:clear`、`view:clear` などと組み合わせて実行されることが多いです。

**影響範囲**：指定されたキャッシュストア内のすべてのキャッシュデータが削除されます。`--tags` オプション使用時は、指定されたタグのキャッシュのみが対象となります。

## バッチ種別

キャッシュ管理 / 運用メンテナンス

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | 随時（デプロイ時・手動） |
| 実行時刻 | 任意 |
| 実行曜日 | - |
| 実行日 | - |
| トリガー | 手動 / デプロイパイプライン |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| キャッシュストア設定 | 対象キャッシュストアが正しく設定されていること |
| ストア接続 | キャッシュストア（Redis、Memcached等）に接続可能なこと |
| ファイル権限 | ファイルキャッシュの場合、キャッシュディレクトリへの書き込み権限 |

### 実行可否判定

特別な実行可否判定なし（常に実行可能）

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| store | string | No | null | クリア対象のキャッシュストア名（引数） |
| --tags | string | No | null | クリア対象のキャッシュタグ（カンマ区切り） |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| キャッシュストア設定 | PHP Config | `config/cache.php` のストア設定 |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| キャッシュストア | DELETE | キャッシュデータの削除 |
| ファイルシステム | DELETE | リアルタイムファサードファイルの削除 |
| コンソール | 標準出力 | 実行結果メッセージ |

### 出力ファイル仕様

ファイル出力なし（削除のみ）

## 処理フロー

### 処理シーケンス

```
1. cache:clearingイベント発火
   └─ ストア名とタグを通知
2. キャッシュフラッシュ
   └─ cache()->flush()またはcache()->tags()->flush()
3. ファサードキャッシュクリア
   └─ storage/framework/cache/facade-*.phpを削除
4. 結果判定
   └─ flush()の戻り値で成功/失敗を判定
5. cache:clearedイベント発火
   └─ ストア名とタグを通知
6. 結果メッセージ出力
```

### フローチャート

```mermaid
flowchart TD
    A[バッチ開始] --> B[cache:clearingイベント発火]
    B --> C{タグ指定あり?}
    C -->|Yes| D[cache->tags->flush]
    C -->|No| E[cache->flush]
    D --> F[flushFacades実行]
    E --> F
    F --> G{flush成功?}
    G -->|No| H[エラーメッセージ出力]
    H --> I[FAILURE終了]
    G -->|Yes| J[cache:clearedイベント発火]
    J --> K[成功メッセージ出力]
    K --> L[SUCCESS終了]
```

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

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

| 処理 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| キャッシュクリア | cache（DBドライバ時） | DELETE | データベースキャッシュストア使用時のみ |

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

データベースキャッシュドライバ使用時のみ、キャッシュテーブルのレコードが削除されます。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| FAILURE | フラッシュ失敗 | flush()がfalseを返した場合 | 権限設定やストア接続を確認 |
| ConnectionException | 接続エラー | Redis/Memcached接続失敗 | ストア接続設定を確認 |
| IOException | ファイルエラー | ファイルキャッシュ削除失敗 | ディレクトリ権限を確認 |

### リトライ仕様

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

### 障害時対応

1. エラーメッセージを確認し、原因を特定
2. キャッシュストアの接続設定を確認
3. ファイルキャッシュの場合、ディレクトリ権限を確認
4. 手動でキャッシュファイル/キーを削除

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

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

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | キャッシュエントリ数に依存 |
| 目標処理時間 | 通常は数秒以内 |
| メモリ使用量上限 | 低メモリ使用 |

## 排他制御

- 同時実行：可能（ただし競合の可能性あり）
- ロック機構：なし
- 注意：クリア中のキャッシュ読み取りは予期しない結果となる可能性

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| 終了ログ（成功） | フラッシュ成功時 | "Application cache cleared successfully." |
| 終了ログ（失敗） | フラッシュ失敗時 | "Failed to clear cache. Make sure you have the appropriate permissions." |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| エラー件数 | 1件以上 | 運用担当者 |

## 備考

- `cache:clearing` と `cache:cleared` イベントにリスナーを登録することで、キャッシュクリア前後にカスタム処理を実行できます
- `--tags` オプションはタグ対応のキャッシュドライバ（Redis、Memcached等）でのみ有効です
- ファイルキャッシュの場合、`storage/framework/cache` ディレクトリ内のファイルが削除されます
- リアルタイムファサードのキャッシュ（`facade-*.php`）も同時にクリアされます
- キャッシュストアを指定しない場合、デフォルトのキャッシュストアが使用されます
