# バッチ設計書 26-cache:prune-stale-tags

## 概要

本ドキュメントは、Laravelフレームワークの古いキャッシュタグ削除コマンド `cache:prune-stale-tags` の設計仕様を定義します。

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

`cache:prune-stale-tags` コマンドは、Redisキャッシュストアで使用される古い（stale）キャッシュタグを削除するバッチ処理です。Redisのタグベースキャッシュ機能では、タグと関連するキャッシュキーの関係性を追跡するためのメタデータが蓄積されます。キャッシュエントリが期限切れになっても、これらのタグメタデータは残存するため、本バッチによる定期的なクリーンアップが必要です。

**業務上の目的・背景**：Laravelのタグベースキャッシュ機能を使用すると、関連するキャッシュエントリをグループ化し、タグ単位で一括無効化できます。しかし、Redisでは各タグに対してセット型のメタデータが作成され、キャッシュエントリの有効期限が切れてもこのメタデータは自動的には削除されません。長期運用においてこれらの古いタグ情報が蓄積されると、メモリ使用量の増加やパフォーマンス低下を引き起こす可能性があります。本バッチは、これらの不要なタグメタデータを削除し、Redisのメモリ効率を維持します。

**バッチの実行タイミング**：主に以下のタイミングで実行されます。
- 日次の定期メンテナンスジョブとして（Scheduler経由）
- Redisメモリ使用量が閾値を超えた場合
- キャッシュタグを大量に使用するアプリケーションでの定期クリーンアップ

**主要な処理内容**：
1. 指定されたキャッシュストア（またはデフォルトストア）を取得
2. ストアが `flushStaleTags` メソッドをサポートしているか確認
3. サポートしている場合、`flushStaleTags()` を実行して古いタグを削除
4. 完了メッセージを出力

**前後の処理との関連**：`cache:clear` とは異なり、キャッシュデータ自体は保持したまま、不要なタグメタデータのみを削除します。定期的なメンテナンスジョブの一部として、他のキャッシュ関連コマンドと組み合わせて実行されることがあります。

**影響範囲**：Redisキャッシュストアの古いタグメタデータが削除されます。有効なキャッシュエントリには影響しません。

## バッチ種別

キャッシュ管理 / 定期メンテナンス

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | 日次（推奨） |
| 実行時刻 | 深夜帯（低負荷時間帯推奨） |
| 実行曜日 | 毎日 |
| 実行日 | - |
| トリガー | cron / 手動 |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| Redisキャッシュ | キャッシュドライバがRedisであること |
| flushStaleTags対応 | キャッシュストアが `flushStaleTags` メソッドをサポートしていること |

### 実行可否判定

1. キャッシュストアが `flushStaleTags` メソッドを持つこと（method_exists チェック）

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| store | string | No | null | 対象のキャッシュストア名（引数） |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| キャッシュストア設定 | PHP Config | `config/cache.php` のストア設定 |
| Redisタグメタデータ | Redis Set | 各タグに関連するキャッシュキーのセット |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| Redisキャッシュ | DELETE | 古いタグメタデータの削除 |
| コンソール | 標準出力 | 実行完了メッセージ |

### 出力ファイル仕様

ファイル出力なし

## 処理フロー

### 処理シーケンス

```
1. キャッシュストア取得
   └─ CacheManager::store()で指定ストアを取得
2. flushStaleTags対応チェック
   └─ method_exists()でメソッド存在確認
3. 古いタグ削除
   └─ flushStaleTags()実行（対応している場合のみ）
4. 完了メッセージ出力
   └─ "Stale cache tags pruned successfully."
```

### フローチャート

```mermaid
flowchart TD
    A[バッチ開始] --> B[キャッシュストア取得]
    B --> C{flushStaleTags対応?}
    C -->|Yes| D[flushStaleTags実行]
    D --> E[完了メッセージ出力]
    C -->|No| E
    E --> F[正常終了]
```

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

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

データベース操作なし（Redis専用機能）

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

なし

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| ConnectionException | Redis接続エラー | Redis接続失敗 | Redis接続設定を確認 |
| RedisException | Redisエラー | Redis操作失敗 | Redisサーバーの状態を確認 |

### リトライ仕様

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

### 障害時対応

1. エラーメッセージを確認し、原因を特定
2. Redis接続設定を確認
3. Redisサーバーの状態を確認
4. 手動でRedisのタグ関連キーを確認・削除

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

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

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | タグ数に依存 |
| 目標処理時間 | タグ数に依存（通常は数秒以内） |
| メモリ使用量上限 | 低メモリ使用 |

## 排他制御

- 同時実行：可能
- ロック機構：なし
- 注意：大量のタグがある場合、処理時間が増加する可能性

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| 終了ログ | バッチ終了時 | "Stale cache tags pruned successfully." |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| Redisメモリ使用量 | 設定閾値超過時 | 運用担当者 |
| エラー件数 | 1件以上 | 開発者 |

## 備考

- このコマンドはRedis専用です。他のキャッシュドライバ（file、database、memcached等）では効果がありません
- `flushStaleTags` メソッドがサポートされていないストアでは、何も実行されずに成功メッセージが表示されます
- タグベースキャッシュを頻繁に使用するアプリケーションでは、日次での定期実行を推奨します
- 大量のタグがある場合、Redis への負荷が一時的に増加する可能性があります
- Schedulerでの定期実行例：`$schedule->command('cache:prune-stale-tags')->hourly();`
