# バッチ設計書 21-db:seed

## 概要

本ドキュメントは、Laravelフレームワークのデータベースシーディングコマンド `db:seed` の設計仕様を定義します。

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

`db:seed` コマンドは、データベースに初期データ（シードデータ）を投入するためのバッチ処理です。開発環境やテスト環境でのデータ準備、本番環境での初期マスターデータ投入など、アプリケーションの動作に必要なデータを効率的にデータベースへ登録します。

**業務上の目的・背景**：アプリケーション開発において、開発者がテストやデモンストレーションのために手動でデータを入力する作業は非効率的です。本バッチは、Seederクラスで定義されたデータ投入ロジックを実行することで、再現可能かつ自動化されたデータ投入を実現します。これにより、開発環境の構築時間短縮、テストデータの一貫性確保、チーム間でのデータ共有が可能になります。

**バッチの実行タイミング**：主に以下のタイミングで実行されます。
- 開発環境の初期セットアップ時
- マイグレーション実行後（`migrate --seed` オプション使用時）
- テストデータのリフレッシュが必要な場合
- 新規環境構築時のマスターデータ投入

**主要な処理内容**：
1. 本番環境の場合、`--force` オプションまたは確認プロンプトによる実行確認を行う
2. 指定されたデータベース接続に切り替える
3. Eloquentモデルのガード機能を一時的に無効化（unguarded状態）
4. 指定されたSeederクラス（デフォルトは `DatabaseSeeder`）をインスタンス化して実行
5. 元のデータベース接続に復元

**前後の処理との関連**：`migrate` コマンドとの連携が多く、`migrate --seed` オプションでマイグレーション直後に自動実行されます。また、`migrate:fresh --seed` でデータベースをクリーンな状態から再構築する際にも使用されます。

**影響範囲**：指定されたSeederクラスが操作するすべてのデータベーステーブルに影響します。Seederの実装によっては既存データの上書きや追加が発生する可能性があります。

## バッチ種別

データ投入 / 初期データセットアップ

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | 随時（手動実行） |
| 実行時刻 | 任意 |
| 実行曜日 | - |
| 実行日 | - |
| トリガー | 手動 / マイグレーション連携 |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| データベース接続 | 対象データベースへの接続が確立されていること |
| Seederクラス | 指定されたSeederクラスが存在し、`run` メソッドが実装されていること |
| テーブル存在 | Seederが操作するテーブルがマイグレーション済みであること |
| 本番環境での実行 | `--force` オプション指定または対話的確認での承認 |

### 実行可否判定

1. `Prohibitable` トレイトによる実行禁止チェック
2. 本番環境での `ConfirmableTrait` による確認（`--force` オプションでスキップ可能）
3. 指定されたSeederクラスの存在確認

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| class | string | No | Database\Seeders\DatabaseSeeder | 実行するSeederクラス名（引数またはオプション） |
| --class | string | No | Database\Seeders\DatabaseSeeder | 実行するSeederクラス名（オプション） |
| --database | string | No | config値 | 使用するデータベース接続名 |
| --force | bool | No | false | 本番環境で確認なしに実行 |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| Seederクラス | PHP Class | `Database\Seeders` 名前空間下のSeederクラス |
| 設定ファイル | PHP Config | `config/database.php` のデフォルト接続設定 |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| データベーステーブル | DB | Seederで定義されたINSERT/UPDATE操作の結果 |
| コンソール | 標準出力 | 実行ステータスメッセージ |

### 出力ファイル仕様

ファイル出力なし

## 処理フロー

### 処理シーケンス

```
1. 実行可否チェック
   └─ Prohibitable/ConfirmableTraitによる確認
2. 開始メッセージ出力
   └─ "Seeding database."
3. データベース接続切り替え
   └─ 現在の接続を保存し、指定接続に切り替え
4. Seeder実行
   └─ Model::unguarded()内でSeederを実行
5. 接続復元
   └─ 元のデータベース接続に戻す
6. 終了
```

### フローチャート

```mermaid
flowchart TD
    A[バッチ開始] --> B{実行禁止チェック}
    B -->|禁止| C[FAILURE終了]
    B -->|許可| D{本番環境確認}
    D -->|拒否| C
    D -->|承認| E[開始メッセージ出力]
    E --> F[DB接続切り替え]
    F --> G[Model::unguarded開始]
    G --> H[Seeder実行]
    H --> I[Model::unguarded終了]
    I --> J{元の接続あり?}
    J -->|あり| K[DB接続復元]
    J -->|なし| L[正常終了]
    K --> L
```

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

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

| 処理 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| シーディング | Seeder定義依存 | INSERT/UPDATE | Seederクラスで定義された任意のデータ操作 |

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

Seederクラスの実装に依存するため、具体的なテーブル操作はSeederクラスを参照してください。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| FAILURE | 実行禁止 | Prohibitableで禁止設定時 | 禁止設定を解除 |
| FAILURE | 確認拒否 | 本番環境で確認を拒否 | `--force` オプション使用または確認で承認 |
| InvalidArgumentException | Seederエラー | `run` メソッド未実装 | Seederクラスに `run` メソッドを実装 |
| ClassNotFoundException | クラス不在 | 指定Seederクラスが存在しない | クラス名を確認し、正しいクラスを指定 |

### リトライ仕様

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

### 障害時対応

1. エラーメッセージを確認し、原因を特定
2. Seederクラスの実装を確認
3. データベース接続設定を確認
4. 必要に応じてロールバック（トランザクションがSeeder内で設定されている場合）

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

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

注意：`db:seed` コマンド自体はトランザクション管理を行いません。必要に応じてSeederクラス内で `DB::transaction()` を使用してください。

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | Seeder実装に依存 |
| 目標処理時間 | Seeder実装に依存 |
| メモリ使用量上限 | PHP設定に依存 |

## 排他制御

- 同時実行：可能（ただし同一データへの書き込み競合に注意）
- ロック機構：コマンドレベルでのロックなし
- 注意：複数のシーディングが同時実行される場合、データの整合性はSeederの実装に依存

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| 開始ログ | バッチ開始時 | "Seeding database." |
| 進捗ログ | Seeder実行時 | 各Seederの実行状況とタイミング |
| 終了ログ | バッチ終了時 | - |
| エラーログ | エラー発生時 | 例外メッセージ |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| 処理時間 | アプリケーション設定に依存 | - |
| エラー件数 | 1件以上 | 開発者/運用担当者 |

## 備考

- `Model::unguarded()` により、シーディング中はEloquentのマスアサインメント保護が無効化されます
- Seederクラスでは `call()` メソッドを使用して他のSeederを呼び出すことができます
- `WithoutModelEvents` トレイトを使用することで、シーディング中のモデルイベントを抑制できます
