# バッチ設計書 5-migrate-product-shipping-profile

## 概要

本ドキュメントはMedusaフレームワークのmigrate-product-shipping-profileマイグレーションスクリプトについて、その設計内容を記述したバッチ設計書です。本スクリプトは製品をデフォルト配送プロファイルに割り当てるマイグレーション処理を実行します。

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

migrate-product-shipping-profileは、すべての製品をデフォルトの配送プロファイル（Shipping Profile）にリンクするマイグレーションスクリプトです。Fulfillmentモジュールの導入やアップグレード時に、既存の製品に配送プロファイルが設定されていない場合に使用されます。

**業務上の目的・背景**：Medusaでは、製品の配送方法を管理するために配送プロファイル（Shipping Profile）という概念を使用しています。配送プロファイルは、どの配送オプションが製品に適用可能かを定義します。新規にFulfillmentモジュールを導入した場合や、既存システムをアップグレードした場合、既存の製品に配送プロファイルが設定されていない可能性があります。このスクリプトは、すべての製品にデフォルトの配送プロファイルを割り当てることで、配送機能が正しく動作することを保証します。

**バッチの実行タイミング**：`db:migrate:scripts`コマンドの実行時に、他のマイグレーションスクリプトと共に実行されます。手動でのCLI実行が必要です。

**主要な処理内容**：
1. FulfillmentモジュールとProductモジュールのインストール確認
2. 既存の配送プロファイルを取得（"default"を含む名前を優先）
3. 配送プロファイルが存在しない場合は新規作成
4. すべての製品と配送プロファイルのリンクを作成

**前後の処理との関連**：`db:migrate`コマンドの後に`db:migrate:scripts`経由で実行されます。FulfillmentモジュールとProductモジュールがインストールされている必要があります。

**影響範囲**：ProductモジュールとFulfillmentモジュール間のリンクテーブルが更新されます。すべての製品が影響を受ける可能性があります。

## バッチ種別

マイグレーションスクリプト / データ連携

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | 随時（マイグレーション時） |
| 実行時刻 | 手動実行 |
| 実行曜日 | N/A |
| 実行日 | N/A |
| トリガー | `db:migrate:scripts`コマンド |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| Fulfillmentモジュールインストール | `MedusaModule.isInstalled(Modules.FULFILLMENT)`がtrue |
| Productモジュールインストール | `MedusaModule.isInstalled(Modules.PRODUCT)`がtrue |
| データベース接続 | 有効なデータベース接続が確立されていること |

### 実行可否判定

- FulfillmentモジュールまたはProductモジュールが未インストールの場合はスキップ（エラーなし）
- マイグレーションスクリプトテーブルで実行済みとして記録されている場合はスキップ

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| container | MedusaContainer | Yes | - | Medusaの依存性注入コンテナ（ExecArgs経由） |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| shipping_profile | DB | 既存の配送プロファイル |
| product | DB | 全製品データ |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| リンクテーブル | DB | Product-ShippingProfileのリンク |
| shipping_profile | DB | 新規作成された配送プロファイル（存在しない場合） |

### 出力ファイル仕様

ファイル出力なし

## 処理フロー

### 処理シーケンス

```
1. モジュールインストール確認
   └─ Fulfillment, Productモジュールの存在チェック
2. 配送プロファイル取得
   └─ useQueryGraphStepで全配送プロファイルを取得
3. 製品一覧取得
   └─ useQueryGraphStepで全製品IDを取得
4. デフォルト配送プロファイル特定
   └─ "default"を含む名前を優先、なければ最初のプロファイル
5. 配送プロファイル作成（必要な場合）
   └─ when条件で存在チェック後、createShippingProfilesStepで作成
6. リンク作成
   └─ createRemoteLinkStepで製品と配送プロファイルをリンク
```

### フローチャート

```mermaid
flowchart TD
    A[スクリプト開始] --> B{Fulfillmentモジュール存在?}
    B -->|No| C[スキップ]
    B -->|Yes| D{Productモジュール存在?}
    D -->|No| C
    D -->|Yes| E[配送プロファイル取得]
    E --> F[製品一覧取得]
    F --> G{デフォルトプロファイル存在?}
    G -->|No| H[新規作成]
    G -->|Yes| I[既存を使用]
    H --> J[リンク作成]
    I --> J
    J --> K[完了ログ出力]
    K --> L[終了]
    C --> L
```

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

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

| 処理 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| 配送プロファイル取得 | shipping_profile | SELECT | 全配送プロファイルを取得 |
| 製品取得 | product | SELECT | 全製品IDを取得 |
| 配送プロファイル作成 | shipping_profile | INSERT | デフォルト配送プロファイルを作成（必要時） |
| リンク作成 | product_shipping_profile | INSERT | 製品と配送プロファイルのリンクを作成 |

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

#### shipping_profile

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | id, name | 全件取得 | - |
| INSERT | name, type | "Default Shipping Profile", "default" | 存在しない場合のみ |

#### product

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | id | 全件取得 | - |

#### product_shipping_profile（リンクテーブル）

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| INSERT | product_id, shipping_profile_id | 各製品ID, デフォルトプロファイルID | createRemoteLinkStep経由 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | 一般エラー | ワークフロー実行失敗 | エラーログ出力、catchブロックで捕捉 |

### リトライ仕様

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

### 障害時対応

- エラー発生時はlogger.errorでエラー内容を出力
- ワークフロー内のトランザクションはロールバック
- 再実行時は最初から処理を行う

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

| 項目 | 内容 |
|-----|------|
| トランザクション範囲 | ワークフロー全体 |
| コミットタイミング | ワークフロー正常完了時 |
| ロールバック条件 | ワークフロー内でエラー発生時 |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | 製品数に依存 |
| 目標処理時間 | 製品数に依存 |
| メモリ使用量上限 | 製品数に依存 |

## 排他制御

マイグレーションスクリプトテーブルにより、同一スクリプトの重複実行を防止します。

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| 情報ログ | 処理開始時 | `Assigning products to shipping profile` |
| 情報ログ | 処理完了時 | `Products assigned to shipping profile` |
| エラーログ | エラー発生時 | エラー内容 |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| 処理失敗 | 発生時 | コンソールログ |

## 備考

- ワークフロー名: `assign-products-to-shipping-profile`
- デフォルト配送プロファイルの判定: 名前に"default"（大文字小文字無視）を含むものを優先
- 存在しない場合は`name: "Default Shipping Profile"`, `type: "default"`で新規作成
- リンクはModules.PRODUCTのproduct_idとModules.FULFILLMENTのshipping_profile_idの組み合わせ
- 実装箇所: `packages/medusa/src/migration-scripts/migrate-product-shipping-profile.ts`
