# 機能設計書 8-シーダー

## 概要

本ドキュメントは、Laravel Frameworkのシーダー機能について、その設計思想、処理フロー、および実装詳細を記述したものである。データベースへの初期データ・テストデータ投入機能の設計を定義する。

### 本機能の処理概要

シーダー機能は、データベースにサンプルデータやマスターデータを投入するための機能である。Seederクラスを継承してrun()メソッドを実装し、Artisanコマンドから実行する。他のシーダーを呼び出すことで、依存関係のあるデータ投入も管理できる。

**業務上の目的・背景**：開発環境やテスト環境で一貫したテストデータを用意することは、品質保証とデバッグに不可欠である。シーダーはデータ投入をコードとして管理し、環境構築の自動化とデータの再現性を実現する。

**機能の利用シーン**：
- 開発環境でのダミーデータ投入
- マスターデータ（都道府県、カテゴリ等）の初期投入
- テスト環境のセットアップ
- デモ環境のデータ準備
- 本番環境での初期データ投入

**主要な処理内容**：
1. Seederクラスの解決とインスタンス化
2. run()メソッドの実行
3. 他のシーダーの呼び出し（call/callWith）
4. 一度だけ実行（callOnce）
5. 実行状況のコンソール出力

**関連システム・外部連携**：
- DIコンテナ（シーダーのインスタンス化）
- Console Command（Artisanコマンド）
- Model Factory（ダミーデータ生成）
- Eloquent ORM（データ挿入）

**権限による制御**：シーダーは通常、開発者・運用者のみが実行可能。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | - | - | CLI機能のため直接関連画面なし |

## 機能種別

データベース管理 / データ投入 / テスト支援

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| class | string\|array | No | 実行するシーダークラス | - |
| silent | bool | No | 出力を抑制 | - |
| parameters | array | No | run()に渡すパラメータ | - |

### 入力データソース

- database/seedersディレクトリ
- Artisan CLI（db:seed）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| - | - | 戻り値なし（データ挿入のみ） |

### 出力先

- データベース（INSERTされたデータ）
- Console出力（実行状況）

## 処理フロー

### 処理シーケンス

```
1. シーダー解決
   └─ resolve()でクラスをインスタンス化
2. コンテナ設定
   └─ setContainer()でDIコンテナを設定
3. コマンド設定
   └─ setCommand()でコンソールコマンドを設定
4. 実行
   └─ __invoke()でrun()メソッドを呼び出し
5. 子シーダー呼び出し
   └─ call()で他のシーダーを実行
```

### フローチャート

```mermaid
flowchart TD
    A[db:seed実行] --> B[SeederClass解決]
    B --> C[setContainer()]
    C --> D[setCommand()]
    D --> E[__invoke()]
    E --> F{run()メソッドあり?}
    F -->|No| G[InvalidArgumentException]
    F -->|Yes| H{WithoutModelEvents?}
    H -->|Yes| I[イベント抑制で実行]
    H -->|No| J[通常実行]
    I --> K[run()呼び出し]
    J --> K
    K --> L{call()呼び出し?}
    L -->|Yes| M[子シーダー解決]
    M --> N[子シーダー実行]
    N --> L
    L -->|No| O[完了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | run()必須 | シーダーはrun()メソッドを実装する必要がある | __invoke()時 |
| BR-02 | 呼び出し記録 | called配列で呼び出し済みシーダーを管理 | call()時 |
| BR-03 | 一度だけ実行 | callOnce()で同一シーダーの重複実行を防止 | callOnce()時 |
| BR-04 | サイレントモード | silent=trueで出力を抑制 | callSilent()時 |

### 計算ロジック

特になし（シーダー内の実装に依存）

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| run() | 各テーブル | INSERT | シーダー内で定義されたデータ挿入 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | InvalidArgumentException | run()メソッドがない | run()メソッドを実装 |
| - | BindingResolutionException | クラスが解決できない | クラス名を確認 |

### リトライ仕様

シーダーにリトライ機能はない。

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

シーダー自体はトランザクションを管理しない。必要に応じてDB::transaction()を使用。

## パフォーマンス要件

- 大量データ投入時はchunk()やbulk insertを使用
- Model Factoryの使用を推奨

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

- 本番環境でのシーダー実行は慎重に
- テストデータに実際のユーザー情報を含めない
- パスワードはHash::make()を使用

## 備考

- `--class`オプションで特定のシーダーのみ実行可能
- Model Factoryと組み合わせて大量のダミーデータを生成
- WithoutModelEventsトレイトでモデルイベントを抑制可能

---

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

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

### 推奨読解順序

#### Step 1: Seederクラスを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Seeder.php | `src/Illuminate/Database/Seeder.php` | シーダー基底クラス |

**主要処理フロー**:
- **19-27行目**: container, command, calledプロパティ
- **43-74行目**: call()メソッド - 他のシーダーを呼び出し
- **83-86行目**: callWith()メソッド - パラメータ付き呼び出し
- **95-98行目**: callSilent()メソッド - サイレント実行
- **107-118行目**: callOnce()メソッド - 一度だけ実行
- **126-141行目**: resolve()メソッド - シーダーのインスタンス化
- **149-154行目**: setContainer()メソッド
- **162-167行目**: setCommand()メソッド
- **177-194行目**: __invoke()メソッド - 実行エントリポイント

**読解のコツ**: Seederは抽象クラスではなく、run()メソッドの実装を前提としたベースクラス。__invoke()でrun()を呼び出すマジックメソッドパターン。

#### Step 2: WithoutModelEventsトレイトを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | WithoutModelEvents.php | `src/Illuminate/Database/Console/Seeds/WithoutModelEvents.php` | モデルイベント抑制 |

**読解ポイント**:
- withoutModelEvents()メソッドでイベント抑制付き実行

#### Step 3: SeedCommandを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | SeedCommand.php | `src/Illuminate/Database/Console/Seeds/SeedCommand.php` | db:seedコマンド |

**読解ポイント**:
- handle()でシーダー実行
- getSeeder()でシーダークラス取得

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

```
php artisan db:seed
    │
    └─ SeedCommand::handle()
           │
           ├─ getSeeder()
           │      └─ resolve(DatabaseSeeder::class)
           │
           └─ $seeder->__invoke()
                  │
                  ├─ method_exists($this, 'run') チェック
                  │
                  ├─ [WithoutModelEvents使用時]
                  │      └─ withoutModelEvents($callback)
                  │
                  └─ container->call([$this, 'run'], $parameters)
                         │
                         └─ DatabaseSeeder::run()
                                │
                                └─ $this->call([
                                       UserSeeder::class,
                                       PostSeeder::class,
                                   ])
                                       │
                                       ├─ resolve(UserSeeder::class)
                                       │      ├─ setContainer()
                                       │      └─ setCommand()
                                       │
                                       └─ UserSeeder::__invoke()
                                              └─ UserSeeder::run()
```

### データフロー図

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

db:seed ───────────────▶ SeedCommand ───────────────────▶ Console出力
                              │
                              ▼
                        Seeder::__invoke()
                              │
                              ▼
                        Seeder::run()
                              │
                              ├── call() ────────────────▶ 子Seeder
                              │
                              └── Model/DB操作 ──────────▶ データベース
                                      │
                                      └── INSERT
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Seeder.php | `src/Illuminate/Database/Seeder.php` | ソース | シーダー基底クラス |
| SeedCommand.php | `src/Illuminate/Database/Console/Seeds/SeedCommand.php` | ソース | db:seedコマンド |
| WithoutModelEvents.php | `src/Illuminate/Database/Console/Seeds/WithoutModelEvents.php` | ソース | モデルイベント抑制トレイト |
| DatabaseSeeder.php | `database/seeders/DatabaseSeeder.php` | ユーザーコード | アプリケーションのメインシーダー |
