# バッチ設計書 20-migrate:status

## 概要

本ドキュメントは、Laravelフレームワークの`migrate:status`コマンドの設計仕様を定義するものです。このコマンドは、各マイグレーションの実行状態を表示するためのArtisanコマンドです。

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

**業務上の目的・背景**：データベースマイグレーションを管理する上で、どのマイグレーションが実行済みで、どのマイグレーションが未実行かを把握することは重要です。本コマンドは、マイグレーションファイルと実行履歴を照合し、各マイグレーションのステータス（実行済み/未実行）とバッチ番号を一覧表示します。デプロイ前の確認、トラブルシューティング、開発環境の状態確認などに使用されます。

**バッチの実行タイミング**：随時（参照のみの確認コマンド）。マイグレーション実行前後の確認、環境間の状態比較、問題調査時などに実行されます。

**主要な処理内容**：
1. マイグレーションテーブルの存在確認
2. 実行済みマイグレーション一覧の取得
3. マイグレーションファイル一覧との照合
4. 各マイグレーションのステータス（Ran/Pending）とバッチ番号を表示

**前後の処理との関連**：`migrate`実行前の確認、`migrate:rollback`後の確認、デプロイ前の環境確認などで使用されます。データを変更しない参照専用コマンドです。

**影響範囲**：参照のみ。データベースへの書き込みは行いません。

## バッチ種別

データベース管理 / 参照・確認

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | 随時 |
| 実行時刻 | - |
| 実行曜日 | - |
| 実行日 | - |
| トリガー | 手動 |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| データベース接続 | 対象データベースへの接続が可能であること |
| マイグレーションテーブル | migrationsテーブルが存在すること（存在しない場合はエラー） |

### 実行可否判定

マイグレーションテーブルが存在しない場合はエラーメッセージを表示して終了コード1を返す。

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| --database | string | No | default | 使用するデータベース接続名 |
| --pending | integer/false | No | false | 未実行のマイグレーションのみ表示（値を指定すると終了コードとして使用） |
| --path | string[] | No | - | マイグレーションファイルのパス |
| --realpath | boolean | No | false | pathが絶対パスであることを示す |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| database/migrations | PHP | マイグレーションファイル群 |
| migrations | DB | マイグレーション実行履歴テーブル |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| コンソール | テキスト | マイグレーションステータス一覧 |

### 出力ファイル仕様

ファイル出力なし

### 出力形式

```
Migration name                                          Batch / Status
2023_01_01_000000_create_users_table                    [1] Ran
2023_01_02_000000_create_posts_table                    [1] Ran
2023_01_03_000000_create_comments_table                 Pending
```

## 処理フロー

### 処理シーケンス

```
1. データベース接続設定
   └─ --databaseオプションで指定された接続を使用
2. マイグレーションテーブル確認
   └─ repositoryExists()でテーブル存在確認
   └─ 存在しない場合: エラーメッセージ出力して終了コード1
3. 実行済みマイグレーション取得
   └─ repository->getRan()で実行済み一覧取得
   └─ repository->getMigrationBatches()でバッチ番号取得
4. ステータス一覧生成
   └─ ファイル一覧と実行履歴を照合
   └─ 各マイグレーションにRan/Pendingを設定
5. フィルタリング
   └─ --pending指定時: Pendingのみ抽出
6. 結果出力
   └─ マイグレーション名とステータスを2カラムで表示
```

### フローチャート

```mermaid
flowchart TD
    A[バッチ開始] --> B[データベース接続設定]
    B --> C{migrationsテーブル存在?}
    C -->|No| D[エラーメッセージ出力]
    D --> E[終了コード1で終了]
    C -->|Yes| F[実行済みマイグレーション取得]
    F --> G[マイグレーションファイル一覧取得]
    G --> H[ステータス一覧生成]
    H --> I{--pending指定?}
    I -->|Yes| J[Pendingのみ抽出]
    I -->|No| K{マイグレーション存在?}
    J --> K
    K -->|Yes| L[ステータス一覧表示]
    K -->|No| M[メッセージ表示]
    L --> N{--pending かつ Pending存在?}
    M --> O[正常終了]
    N -->|Yes| P[--pending値で終了]
    N -->|No| O
```

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

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

| 処理 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| 実行履歴取得 | migrations | SELECT | 実行済みマイグレーション一覧を取得 |

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

#### migrations

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | migration, batch | 全レコード | getRan(), getMigrationBatches() |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| 1 | テーブル未存在 | migrationsテーブルがない | migrate:installで作成またはmigrateを実行 |
| --pending値 | 未実行あり | --pending指定時にPendingが存在 | migrateを実行 |

### リトライ仕様

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

リトライ機構は実装されていない。

### 障害時対応

- テーブル未存在: `migrate:install`または`migrate`を実行してテーブルを作成

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

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

参照のみのためトランザクションは使用しない。

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | マイグレーションファイル数 |
| 目標処理時間 | 1秒未満 |
| メモリ使用量上限 | 最小限 |

## 排他制御

排他制御なし。参照のみのため同時実行可能。

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| エラーログ | テーブル未存在時 | "Migration table not found." |
| 情報ログ | マイグレーションなし時 | "No migrations found" または "No pending migrations" |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| - | - | - |

参照コマンドのため特別な監視は不要。

## 備考

- Laravel 12.x対応
- 参照専用コマンド（データ変更なし）
- `--pending`オプション: 未実行のマイグレーションのみ表示
- `--pending`に値を指定すると、Pending存在時にその値を終了コードとして返す（CI/CD向け）
- ステータス表示形式
  - `[N] Ran`: バッチ番号Nで実行済み
  - `Pending`: 未実行
- ANSIカラー対応
  - Ran: 緑色
  - Pending: 黄色
- 本番環境確認なし（参照のみのため）
- Prohibitableなし（参照のみのため）
