# バッチ設計書 16-buildSeedScript

## 概要

本ドキュメントは、Medusaフレームワークにおけるモジュール用シードデータ挿入スクリプトビルダー「buildSeedScript」の設計仕様を定義する。

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

buildSeedScriptは、MikroORMベースのMedusaモジュールに対してシードデータを挿入するためのスクリプトを生成するユーティリティ関数である。開発環境やテスト環境で初期データを投入する際に使用される。

**業務上の目的・背景**：開発・テスト環境では、アプリケーションの動作確認や機能テストのために一定量のサンプルデータが必要となる。手動でデータを入力するのは非効率であり、環境の再現性も保証できない。このユーティリティは、シードデータの定義をファイルから読み込み、モジュール固有のハンドラを通じて一貫した方法でデータを挿入することで、開発効率と環境の再現性を向上させる。

**バッチの実行タイミング**：新規環境構築後、テストデータが必要な際に手動で実行される。また、CI/CDパイプラインでテスト環境を構築する際にも使用される。

**主要な処理内容**：
1. モジュール名、モデル、マイグレーションパス、シードハンドラを受け取りスクリプト関数を生成
2. 指定されたパスからシードデータをdynamic import
3. データベース設定の読み込み（loadDatabaseConfig）
4. MikroORM接続の作成とEntityManagerの取得
5. シードハンドラによるデータ挿入の実行

**前後の処理との関連**：db:migrateの後に実行される。マイグレーションでスキーマが準備された後、シードデータを投入する。

**影響範囲**：指定されたモジュールのデータベーステーブルへのデータ挿入。

## バッチ種別

データ投入（シーディング）

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | 随時（環境構築時） |
| 実行時刻 | 任意 |
| 実行曜日 | 該当なし |
| 実行日 | 該当なし |
| トリガー | 手動実行 / CI/CD |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| PostgreSQL接続可能 | データベースサーバーに接続できること |
| マイグレーション実行済み | テーブルが作成されていること |
| シードデータファイル存在 | pathパラメータで指定されたファイルが存在すること |
| MikroORMベースモジュール | このユーティリティはMikroORMを使用するモジュールでのみ有効 |

### 実行可否判定

1. シードデータファイルをdynamic importで読み込み
2. ファイルがスキップ対象でないことを確認（isFileSkipped）
3. loadDatabaseConfigでデータベース設定を取得

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| moduleName | string | Yes | - | モジュール名（ログ出力に使用） |
| models | Record<string, unknown> | Yes | - | モジュールのモデル定義 |
| pathToMigrations | string | Yes | - | マイグレーションファイルのディレクトリパス |
| seedHandler | function | Yes | - | シードデータ挿入を実行するハンドラ関数 |

### seedHandler関数のシグネチャ

```typescript
seedHandler: (args: {
  manager: any
  logger: Logger
  data: any
}) => Promise<void>
```

### 生成される関数のパラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| options | ModuleServiceInitializeOptions | No | {} | モジュール初期化オプション |
| logger | Logger | No | console | ログ出力用Logger |
| path | string | Yes | - | シードデータファイルのパス |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| シードデータファイル | JavaScript/TypeScript | exportされたシードデータ |
| データベース設定 | 設定オブジェクト | loadDatabaseConfigから取得 |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| モジュールテーブル | DBテーブル | シードデータが挿入される |
| 標準出力 | コンソール | 実行ログ |

### 出力ファイル仕様

ファイル出力はなし。

## 処理フロー

### 処理シーケンス

```
1. buildSeedScript呼び出し
   └─ moduleName、models、pathToMigrations、seedHandlerを受け取り関数を生成
2. 生成された関数の実行
   └─ options、logger、pathを受け取る
3. シードデータファイル読み込み
   └─ dynamicImport(resolve(process.cwd(), path))
4. スキップチェック
   └─ isFileSkipped(dataSeed)
5. データベース設定読み込み
   └─ loadDatabaseConfig(moduleName, options)
6. MikroORM接続作成
   └─ mikroOrmCreateConnection(dbData, entities, pathToMigrations)
7. EntityManager取得
   └─ orm.em.fork()
8. シードハンドラ実行
   └─ seedHandler({ manager, logger, data: dataSeed })
9. ORM接続クローズ
   └─ orm.close(true)
```

### フローチャート

```mermaid
flowchart TD
    A[buildSeedScript呼び出し] --> B[関数を生成して返却]
    B --> C[生成関数の実行]
    C --> D[Loading seed data ログ]
    D --> E[dynamicImportでシードデータ読み込み]
    E --> F{読み込み成功?}
    F -->|No| G[エラーログ出力]
    G --> H[例外throw]
    F -->|Yes| I{isFileSkipped?}
    I -->|Yes| J[処理終了 早期リターン]
    I -->|No| K[loadDatabaseConfig]
    K --> L[mikroOrmCreateConnection]
    L --> M[orm.em.fork]
    M --> N[Inserting data ログ]
    N --> O[seedHandler実行]
    O --> P{エラー発生?}
    P -->|Yes| Q[エラーログ出力]
    P -->|No| R[orm.close]
    Q --> R
    R --> S[処理終了]
```

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

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

| 処理 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| シードデータ挿入 | モジュールテーブル | INSERT | シードハンドラで定義されたデータを挿入 |

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

具体的な操作内容はseedHandlerの実装に依存する。典型的には以下のようなテーブルにデータが挿入される：

#### 製品モジュールの場合

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| INSERT | product.title | シードデータから | 製品名 |
| INSERT | product.description | シードデータから | 製品説明 |
| INSERT | product_variant.* | シードデータから | バリアント情報 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | ファイル読み込みエラー | シードデータファイルが存在しない/読み込めない | パスを確認、exportを確認 |
| - | 接続エラー | データベースに接続できない | 接続設定を確認 |
| - | データ挿入エラー | 制約違反、データ不整合 | シードデータを確認 |

### リトライ仕様

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

### 障害時対応

1. エラーログを確認し、失敗箇所を特定
2. シードデータファイルのパスと内容を確認
3. データ挿入エラーの場合はシードデータの整合性を確認
4. 既存データとの競合がある場合はデータベースをクリアして再実行

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

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

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | シードデータ量による |
| 目標処理時間 | シードデータ量による |
| メモリ使用量上限 | Node.jsデフォルト制限 |

## 排他制御

同一モジュールに対する同時実行は想定していない。本番環境での実行は推奨されない。

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| 開始ログ | シードデータ読み込み時 | Loading seed data from {path}... |
| 進捗ログ | データ挿入開始時 | Inserting {moduleName} data... |
| エラーログ | ファイル読み込みエラー時 | Failed to load seed data from {path} |
| エラーログ | データ挿入エラー時 | Failed to insert the seed data in the PostgreSQL database {clientUrl} |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| エラー発生 | 1件以上 | 標準エラー出力 |

## 備考

- このユーティリティはMikroORMベースのモジュール専用
- シードデータファイルは相対パスで指定し、process.cwd()からの相対パスとして解決される
- シードデータファイルの必須export項目の例：productCategoriesData、productsData、variantsData
- isFileSkippedでスキップ対象の場合は処理を行わずに終了（return）
- orm.close(true)でORM接続を強制クローズ
- seedHandler内でのエラーはcatchされログ出力されるが、スクリプト全体は続行する（エラーはthrowされない）
