# 機能設計書 44-コマンドバス

## 概要

本ドキュメントは、Laravel Frameworkのコマンドバス（Bus）機能の設計仕様を定義する。Dispatcherクラスを中心とした、コマンド/ジョブのディスパッチ機能について詳述する。

### 本機能の処理概要

コマンドバスは、コマンドパターンとジョブキューを統合した機能を提供する。同期実行、キュー経由の非同期実行、パイプライン処理、バッチ処理、チェーン処理など、様々なジョブ実行パターンをサポートする。

**業務上の目的・背景**：アプリケーションの処理をコマンド（ジョブ）として分離することで、関心の分離が促進され、テストが容易になる。また、時間のかかる処理をキューに投入することで、ユーザーへのレスポンスを高速化し、システムの可用性を向上させる。バッチ処理やチェーン処理により、複数のジョブを協調して実行することも可能。

**機能の利用シーン**：メール送信、ファイル処理、レポート生成、外部API呼び出し、大量データの処理など、時間がかかる処理や非同期で実行したい処理で利用される。

**主要な処理内容**：
1. コマンド/ジョブのディスパッチ（dispatch）
2. 同期実行（dispatchSync、dispatchNow）
3. キュー経由の非同期実行（dispatchToQueue）
4. レスポンス後の実行（dispatchAfterResponse）
5. パイプライン処理（pipeThrough）
6. バッチ処理（batch）
7. チェーン処理（chain）

**関連システム・外部連携**：キューシステム（Queue）、パイプライン（Pipeline）、DIコンテナと連携する。

**権限による制御**：コマンドバス自体には権限制御は存在しないが、各ジョブ内で個別に認可チェックを実装することがある。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | - | - | 画面機能マッピングにコマンドバス関連の画面なし |

## 機能種別

ジョブディスパッチ / 非同期処理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| command | object | Yes | ディスパッチするコマンド/ジョブオブジェクト | - |
| handler | object\|null | No | コマンドを処理するハンドラ | - |

### 入力データソース

- アプリケーションコードからのdispatch()呼び出し
- コントローラからのジョブディスパッチ
- イベントリスナーからのジョブディスパッチ

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| result | mixed | コマンドの実行結果（同期実行時） |
| job_id | string\|null | キューに投入されたジョブのID |

### 出力先

- 呼び出し元への戻り値
- キューストレージ（Database、Redis等）

## 処理フロー

### 処理シーケンス

```
1. ディスパッチ要求受信
   └─ dispatch()メソッドが呼び出される

2. キュー判定
   └─ ShouldQueueインターフェースを実装しているか確認
   └─ queueResolverが設定されているか確認

3. 同期実行の場合
   └─ dispatchNow()でパイプラインを通して即時実行
   └─ handleまたは__invokeメソッドを呼び出し

4. 非同期実行の場合
   └─ dispatchToQueue()でキューに投入
   └─ delayがある場合はlater()で遅延実行

5. パイプライン処理
   └─ 登録されたパイプを順番に通過
   └─ 最終的にハンドラを実行
```

### フローチャート

```mermaid
flowchart TD
    A[dispatch呼び出し] --> B{ShouldQueue<br/>実装?}
    B -->|Yes| C{queueResolver<br/>設定済み?}
    C -->|Yes| D[dispatchToQueue]
    C -->|No| E[dispatchNow]
    B -->|No| E
    D --> F{delayあり?}
    F -->|Yes| G[queue->later]
    F -->|No| H[queue->push]
    E --> I[パイプライン実行]
    I --> J{ハンドラ<br/>登録済み?}
    J -->|Yes| K[ハンドラのhandle呼び出し]
    J -->|No| L[コマンドのhandle呼び出し]
    K --> M[結果返却]
    L --> M
    G --> N[ジョブID返却]
    H --> N
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-44-1 | キュー判定 | ShouldQueueを実装し、queueResolverが設定されている場合のみキュー経由 | commandShouldBeQueued() が true |
| BR-44-2 | ハンドラ優先 | handlersに登録されたハンドラがあればコマンド自身のhandleより優先 | hasCommandHandler() が true |
| BR-44-3 | Syncコネクション | dispatchSync()はsyncコネクションでキュー実行 | dispatchSync呼び出し時 |
| BR-44-4 | レスポンス後実行 | dispatchAfterResponse()はアプリケーション終了時に実行 | terminatingコールバック登録 |

### 計算ロジック

該当なし

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| dispatchToQueue | jobs | INSERT | キュージョブをジョブテーブルに追加 |
| batch | job_batches | INSERT | バッチ情報をバッチテーブルに追加 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| RuntimeException | キュー解決失敗 | queueResolverがQueue実装を返さない | queueResolverの設定を確認 |

### リトライ仕様

キュージョブのリトライはキューワーカーの設定に従う。

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

コマンドバス自体はトランザクション管理を行わない。各ジョブ内で個別にトランザクション制御を実装する。

## パフォーマンス要件

- キュー経由の場合、dispatch時のオーバーヘッドは最小限
- 同期実行時はパイプライン処理のオーバーヘッドが発生

## セキュリティ考慮事項

- キューに投入されるジョブはシリアライズされるため、センシティブデータの取り扱いに注意
- ジョブ内で認可チェックを行う場合、実行時のユーザーコンテキストに注意

## 備考

- dispatch()ヘルパー関数から呼び出すのが一般的
- PendingDispatch、PendingBatch等のfluentインターフェースを提供

---

## コードリーディングガイド

本機能を理解するために参照すべきファイルと、推奨する読み解き順序を以下に示す。

### 推奨読解順序

#### Step 1: データ構造を理解する

Dispatcherが管理する内部状態を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Dispatcher.php | `src/Illuminate/Bus/Dispatcher.php` | プロパティ定義（24-59行目）で管理される状態を把握 |
| 1-2 | QueueingDispatcher.php | `src/Illuminate/Contracts/Bus/QueueingDispatcher.php` | インターフェース定義 |

**読解のコツ**: $pipelineがパイプライン処理を担当し、$pipesがディスパッチ前に通過するパイプのリスト、$handlersがコマンドとハンドラのマッピングを保持する。

#### Step 2: エントリーポイントを理解する

ジョブディスパッチの入口を把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Dispatcher.php | `src/Illuminate/Bus/Dispatcher.php` | dispatch()（77-82行目）がメインエントリーポイント |

**主要処理フロー**:
1. **79-81行目**: queueResolverがありShouldQueueならdispatchToQueue
2. **81行目**: それ以外はdispatchNow

#### Step 3: 同期実行処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Dispatcher.php | `src/Illuminate/Bus/Dispatcher.php` | dispatchNow()（111-134行目） |
| 3-2 | Dispatcher.php | `src/Illuminate/Bus/Dispatcher.php` | dispatchSync()（93-102行目） |

**主要処理フロー**:
- **113-117行目**: InteractsWithQueue使用時はSyncJobを設定
- **119-131行目**: ハンドラがあればハンドラ、なければコマンド自身のhandleを呼び出し
- **133行目**: パイプラインを通してコールバック実行

#### Step 4: キュー実行処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Dispatcher.php | `src/Illuminate/Bus/Dispatcher.php` | dispatchToQueue()（216-231行目） |
| 4-2 | Dispatcher.php | `src/Illuminate/Bus/Dispatcher.php` | pushCommandToQueue()（240-247行目） |

**主要処理フロー**:
- **218行目**: コネクション取得
- **220-224行目**: queueResolverでキューインスタンス取得
- **226-227行目**: コマンドにqueueメソッドがあればそれを使用
- **230行目**: pushCommandToQueueでキューに投入
- **242-243行目**: delayがあればlater、なければpush

#### Step 5: バッチ・チェーン処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 5-1 | Dispatcher.php | `src/Illuminate/Bus/Dispatcher.php` | batch()（152-155行目） |
| 5-2 | Dispatcher.php | `src/Illuminate/Bus/Dispatcher.php` | chain()（163-169行目） |
| 5-3 | PendingBatch.php | `src/Illuminate/Bus/PendingBatch.php` | バッチの詳細設定 |

**主要処理フロー**:
- **154行目**: PendingBatchを作成
- **165-168行目**: ChainedBatch準備後、PendingChainを作成

### プログラム呼び出し階層図

```
dispatch($command) [ヘルパー関数]
    │
    └─ Dispatcher::dispatch($command)
           │
           ├─ commandShouldBeQueued($command)
           │      └─ $command instanceof ShouldQueue
           │
           ├─ [キュー実行]
           │  dispatchToQueue($command)
           │      │
           │      ├─ $queueResolver($connection)
           │      │
           │      └─ pushCommandToQueue($queue, $command)
           │             │
           │             ├─ [遅延あり] queue->later($delay, $command)
           │             │
           │             └─ [即時] queue->push($command)
           │
           └─ [同期実行]
              dispatchNow($command, $handler)
                  │
                  ├─ getCommandHandler($command)
                  │      └─ $handlers[get_class($command)]
                  │
                  └─ Pipeline::send($command)->through($pipes)->then($callback)
                         │
                         └─ $callback($command)
                                │
                                ├─ [ハンドラあり] $handler->handle($command)
                                │
                                └─ [セルフハンドル] $container->call([$command, 'handle'])
```

### データフロー図

```
[入力]                    [処理]                          [出力]

$command         ───▶  dispatch()               ───▶  キュー/即時判定
(ジョブオブジェクト)      (ディスパッチ)

$command         ───▶  dispatchToQueue()        ───▶  jobs テーブル
(ShouldQueue)          (キュー投入)

$command         ───▶  Pipeline::then()         ───▶  実行結果
(通常コマンド)          (パイプライン実行)

[$jobs]          ───▶  batch()                  ───▶  PendingBatch
(ジョブ配列)            (バッチ作成)

[$jobs]          ───▶  chain()                  ───▶  PendingChain
(ジョブ配列)            (チェーン作成)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Dispatcher.php | `src/Illuminate/Bus/Dispatcher.php` | ソース | コマンドバスのメイン実装 |
| BusServiceProvider.php | `src/Illuminate/Bus/BusServiceProvider.php` | ソース | サービスプロバイダ |
| PendingBatch.php | `src/Illuminate/Bus/PendingBatch.php` | ソース | バッチ設定用fluent API |
| Batch.php | `src/Illuminate/Bus/Batch.php` | ソース | バッチ実行状態管理 |
| BatchRepository.php | `src/Illuminate/Bus/BatchRepository.php` | ソース | バッチ永続化インターフェース |
| DatabaseBatchRepository.php | `src/Illuminate/Bus/DatabaseBatchRepository.php` | ソース | データベースバッチリポジトリ |
| ChainedBatch.php | `src/Illuminate/Bus/ChainedBatch.php` | ソース | チェーン内バッチ処理 |
| Queueable.php | `src/Illuminate/Bus/Queueable.php` | ソース | キュー関連トレイト |
| Dispatchable.php | `src/Illuminate/Bus/Dispatchable.php` | ソース | ディスパッチ関連トレイト |
| QueueingDispatcher.php | `src/Illuminate/Contracts/Bus/QueueingDispatcher.php` | コントラクト | インターフェース定義 |
| PendingChain.php | `src/Illuminate/Foundation/Bus/PendingChain.php` | ソース | チェーン設定用fluent API |
