# 画面設計書 54-配送設定

## 概要

本ドキュメントは、Shopware 6 管理画面における配送設定（sw-settings-shipping）画面の設計書です。ECサイトで使用する配送方法の登録・編集・管理を行う画面について記述します。

### 本画面の処理概要

**業務上の目的・背景**：ECサイトにおいて、配送方法の管理は注文処理の根幹をなす重要な機能です。本画面では、配送方法の基本情報、価格計算ルール（価格マトリクス）、配送時間、対象の販売チャネル、利用可能条件（ルール）を設定することで、多様な配送オプションを顧客に提供できます。

**画面へのアクセス方法**：管理画面にログイン後、左メニューの「設定」 > 「配送」をクリックして一覧画面にアクセスします。一覧画面から新規作成ボタンまたは既存の配送方法名をクリックして詳細画面に遷移します。

**主要な操作・処理内容**：
1. 配送方法一覧の表示・検索・ソート
2. 新規配送方法の作成（名前、トラッキングURL、配送時間、ロゴ、説明等）
3. 既存配送方法の編集
4. 価格計算設定（ルール、価格マトリクス）
5. 有効/無効の切り替え
6. 配送方法の削除

**画面遷移**：設定メニュー → 配送方法一覧画面 → 配送方法詳細画面（基本設定/価格設定タブ）。詳細画面から一覧画面への戻り遷移も可能です。

**権限による表示制御**：`shipping.viewer`権限で閲覧可能、`shipping.editor`権限で編集可能、`shipping.creator`権限で新規作成可能、`shipping.deleter`権限で削除可能です。権限がない場合、該当するボタンやアクションは無効化されます。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 37 | チェックアウト | 参照元 | 配送方法の選択 |

## 画面種別

一覧 / 詳細 / 登録 / 編集

## URL/ルーティング

| 画面 | URL | コンポーネント |
|------|-----|---------------|
| 配送方法一覧 | `#/sw/settings/shipping/index` | sw-settings-shipping-list |
| 配送方法詳細（基本設定） | `#/sw/settings/shipping/detail/:id/base` | sw-settings-shipping-detail-base |
| 配送方法詳細（価格設定） | `#/sw/settings/shipping/detail/:id/prices` | sw-settings-shipping-detail-prices |
| 配送方法新規作成 | `#/sw/settings/shipping/create` | sw-settings-shipping-detail-base |

## 入出力項目

### 一覧画面

| 項目名 | 項目ID | 型 | 入力/出力 | 必須 | 説明 |
|--------|--------|-----|----------|------|------|
| 名前 | name | string | 出力 | - | 配送方法の表示名 |
| アクティブ | active | boolean | 出力 | - | 有効/無効状態 |
| 税率 | tax | relation | 出力 | - | 関連する税率 |

### 詳細画面 - 基本設定

| 項目名 | 項目ID | 型 | 入力/出力 | 必須 | 説明 |
|--------|--------|-----|----------|------|------|
| 名前 | name | string | 入力 | ○ | 配送方法の表示名 |
| アクティブ | active | boolean | 入力 | - | 有効/無効状態 |
| トラッキングURL | trackingUrl | string | 入力 | - | 荷物追跡URL（%s で追跡番号を置換） |
| 配送時間 | deliveryTimeId | uuid | 入力 | ○ | 配送時間の選択 |
| ロゴ | mediaId | uuid | 入力 | - | 配送方法のロゴ画像 |
| 税率 | taxId | uuid | 入力 | - | 関連する税率 |
| 税タイプ | taxType | string | 入力 | - | 税計算タイプ（auto/highest/fixed） |
| 説明 | description | text | 入力 | - | 配送方法の説明 |

### 詳細画面 - 価格設定

| 項目名 | 項目ID | 型 | 入力/出力 | 必須 | 説明 |
|--------|--------|-----|----------|------|------|
| ルール | ruleId | uuid | 入力 | - | 価格計算に適用するルール |
| 計算タイプ | calculation | int | 入力 | ○ | 価格計算方法（数量/重量/価格/体積） |
| 通貨 | currencyId | uuid | 入力 | ○ | 価格設定する通貨 |
| 開始値 | quantityStart | float | 入力 | ○ | 価格帯の開始値 |
| 終了値 | quantityEnd | float | 入力 | - | 価格帯の終了値 |
| 配送料 | currencyPrice | float | 入力 | ○ | 配送料金 |

## 表示項目

### 一覧画面

| 項目名 | 説明 |
|--------|------|
| 配送方法名 | 配送方法の表示名（詳細画面へのリンク） |
| アクティブ | 有効/無効状態（ラベル表示） |
| 税率 | 関連する税率名 |

### 詳細画面

| 項目名 | 説明 |
|--------|------|
| 基本設定タブ | 基本情報、配送時間、トラッキング設定等 |
| 価格設定タブ | 配送料金マトリクス、ルールベース価格設定 |
| カスタムフィールド | カスタムフィールドセットが定義されている場合に表示 |

## イベント仕様

### 1-保存ボタン押下

ユーザーが「保存」ボタンを押下すると、入力された配送方法情報がバリデーションされ、shippingMethodリポジトリを通じてAPIに保存リクエストが送信されます。保存成功時は成功通知が表示され、新規作成の場合は詳細画面にリダイレクトされます。

### 2-キャンセルボタン押下

ユーザーが「キャンセル」ボタンを押下すると、変更を破棄して配送方法一覧画面に遷移します。

### 3-削除ボタン押下

一覧画面または詳細画面で削除を実行すると、削除確認モーダルが表示されます。確認後、shippingMethodリポジトリのdeleteメソッドを通じて配送方法が削除されます。

### 4-価格マトリクス追加

価格設定タブで「新しい配送料を追加」ボタンをクリックすると、価格マトリクス入力フォームが表示されます。計算タイプ、価格帯、配送料を入力して保存します。

### 5-ルール選択・クリア

価格設定タブでルールを選択または作成し、そのルールに対して配送料を設定します。ルールを削除する場合は確認モーダルが表示されます。

### 6-メディアアップロード

ロゴ画像をドラッグ&ドロップまたはファイル選択でアップロードします。メディアサイドバーからも選択可能です。

## データベース更新仕様

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| 保存ボタン押下 | shipping_method | INSERT/UPDATE | 配送方法情報の新規作成または更新 |
| 保存ボタン押下 | shipping_method_translation | INSERT/UPDATE | 配送方法の翻訳情報 |
| 価格マトリクス保存 | shipping_method_price | INSERT/UPDATE/DELETE | 配送料金設定 |
| 削除ボタン押下 | shipping_method | DELETE | 配送方法の削除 |

### テーブル別更新項目詳細

#### shipping_method

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| INSERT/UPDATE | id | UUIDv4 | 新規作成時は自動生成 |
| INSERT/UPDATE | name | 入力値 | 配送方法名 |
| INSERT/UPDATE | active | 入力値 | 有効/無効フラグ |
| INSERT/UPDATE | tracking_url | 入力値 | トラッキングURL |
| INSERT/UPDATE | delivery_time_id | 選択値 | 配送時間への外部キー |
| INSERT/UPDATE | media_id | 選択値 | ロゴメディアへの外部キー |
| INSERT/UPDATE | tax_type | 入力値 | 税計算タイプ |
| INSERT/UPDATE | tax_id | 選択値 | 税率への外部キー |

#### shipping_method_price

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| INSERT/UPDATE | id | UUIDv4 | 新規作成時は自動生成 |
| INSERT/UPDATE | shipping_method_id | 親配送方法のID | 外部キー |
| INSERT/UPDATE | rule_id | 選択したルールのID | 外部キー（NULL可） |
| INSERT/UPDATE | calculation | 入力値 | 計算タイプ（1:数量,2:重量,3:価格,4:体積） |
| INSERT/UPDATE | quantity_start | 入力値 | 価格帯開始値 |
| INSERT/UPDATE | quantity_end | 入力値 | 価格帯終了値 |
| INSERT/UPDATE | currency_price | JSON形式 | 通貨別配送料 |

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 | 表示条件 |
|------------|------|--------------|----------|
| messageSaveSuccess | 成功 | 配送方法が正常に保存されました | 保存成功時 |
| messageSaveError | エラー | 配送方法の保存中にエラーが発生しました | 保存失敗時 |
| messageDeleteSuccess | 成功 | 配送方法が正常に削除されました | 削除成功時 |
| placeholderTrackingUrl | 情報 | %s は追跡番号に置き換えられます | トラッキングURL入力時 |

## 例外処理

| 例外ケース | 処理内容 |
|-----------|---------|
| 配送方法が見つからない | エラー通知を表示し、一覧画面にリダイレクト |
| 権限不足 | 該当するアクションボタンを無効化し、ツールチップで警告表示 |
| 通信エラー | エラー通知を表示し、ローディング状態を解除 |
| バリデーションエラー | 該当項目にエラー表示し、保存を中止 |
| 使用中の配送方法削除 | エラー通知を表示（販売チャネルで使用中の場合） |
| 価格マトリクス重複 | 重複警告を表示し、入力修正を促す |

## 備考

- 配送方法は詳細画面が「基本設定」と「価格設定」の2タブで構成されます
- 価格計算タイプは4種類：数量（1）、重量（2）、価格（3）、体積（4）
- 税タイプは「auto」（カート内商品の最高税率）、「highest」、「fixed」から選択
- トラッキングURLの%sは実際の追跡番号に置き換えられます
- カスタムフィールドセットが定義されている場合、詳細画面にカスタムフィールドタブが表示されます

---

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

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

### 推奨読解順序

#### Step 1: データ構造を理解する

配送方法エンティティとその関連データの構造を理解することが重要です。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | ShippingMethodDefinition.php | `src/Core/Checkout/Shipping/` | 配送方法エンティティの定義 |
| 1-2 | ShippingMethodPriceDefinition.php | `src/Core/Checkout/Shipping/Aggregate/ShippingMethodPrice/` | 配送料金の関連エンティティ |

**読解のコツ**: 配送料金はルールと価格マトリクスの組み合わせで構成されます。

#### Step 2: エントリーポイントを理解する

モジュール登録とルーティング設定を確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | index.js | `src/Administration/Resources/app/administration/src/module/sw-settings-shipping/index.js` | モジュール登録、ルート定義、権限設定 |

**主要処理フロー**:
1. **Module.register**: モジュール登録
2. **routes**: index, detail（子ルート含む）, createの定義
3. **settingsItem**: 設定メニューへの追加

#### Step 3: 一覧画面コンポーネントを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | index.js | `src/Administration/Resources/app/administration/src/module/sw-settings-shipping/page/sw-settings-shipping-list/index.js` | 一覧画面のロジック |

**主要処理フロー**:
- **shippingMethodCriteria**: 配送方法一覧取得条件（税率アソシエーション含む）
- **shippingMethodColumns**: グリッドカラム定義
- **getList()**: 配送方法一覧の取得

#### Step 4: 詳細画面コンポーネントを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | index.js | `src/Administration/Resources/app/administration/src/module/sw-settings-shipping/page/sw-settings-shipping-detail/index.js` | 詳細画面のロジック |

**主要処理フロー**:
- **createdComponent()**: 初期化処理
- **loadEntityData()**: 配送方法データの読み込み
- **onSave()**: 保存処理（価格マトリクス含む）
- **mediaCriteria**: ロゴメディアの取得条件

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

```
sw-settings-shipping (モジュール)
    │
    ├─ sw-settings-shipping-list (一覧画面)
    │      ├─ shippingMethodRepository.search() - 一覧取得
    │      └─ shippingMethodRepository.delete() - 削除
    │
    └─ sw-settings-shipping-detail (詳細画面)
           │
           ├─ sw-settings-shipping-detail-base (基本設定タブ)
           │      ├─ shippingMethodRepository.get() - 詳細取得
           │      ├─ shippingMethodRepository.create() - 新規作成
           │      └─ shippingMethodRepository.save() - 保存
           │
           └─ sw-settings-shipping-detail-prices (価格設定タブ)
                  ├─ sw-settings-shipping-price-matrices
                  │      └─ 価格マトリクスの表示・編集
                  └─ ルール選択・作成
```

### データフロー図

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

配送方法フォーム ────▶ sw-settings-shipping-detail ───▶ shipping_method テーブル
                              │
価格マトリクス入力 ───▶       ├─▶ バリデーション
                              │
                              └─▶ shippingMethodRepository.save()
                                        │
                                        ▼
                              Admin API (/api/shipping-method)
                                        │
                                        ▼
                              ShippingMethodRepository (PHP)
                                        │
                                        ├─▶ shipping_method
                                        ├─▶ shipping_method_translation
                                        └─▶ shipping_method_price
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| index.js | `src/Administration/Resources/app/administration/src/module/sw-settings-shipping/index.js` | ソース | モジュール定義 |
| index.js | `src/Administration/Resources/app/administration/src/module/sw-settings-shipping/page/sw-settings-shipping-list/index.js` | ソース | 一覧画面ロジック |
| index.js | `src/Administration/Resources/app/administration/src/module/sw-settings-shipping/page/sw-settings-shipping-detail/index.js` | ソース | 詳細画面ロジック |
| index.js | `src/Administration/Resources/app/administration/src/module/sw-settings-shipping/component/sw-settings-shipping-price-matrices/index.js` | ソース | 価格マトリクスコンポーネント |
| index.js | `src/Administration/Resources/app/administration/src/module/sw-settings-shipping/component/sw-settings-shipping-price-matrix/index.js` | ソース | 価格マトリクス単体コンポーネント |
| index.js | `src/Administration/Resources/app/administration/src/module/sw-settings-shipping/component/sw-settings-shipping-tax-cost/index.js` | ソース | 税率設定コンポーネント |
| index.js | `src/Administration/Resources/app/administration/src/module/sw-settings-shipping/acl/index.js` | ソース | 権限定義 |
