# 画面設計書 143-配送プロファイル作成画面

## 概要

本ドキュメントは、Medusa Admin Dashboard における配送プロファイル作成画面の設計仕様を記述したものである。

### 本画面の処理概要

**業務上の目的・背景**：配送プロファイルは商品の配送方法を分類するための重要な設定である。新しい配送要件（例：生鮮食品専用、割れ物専用、海外発送専用など）が発生した場合、管理者は新しい配送プロファイルを作成し、それを該当商品に紐付けることで、適切な配送オプションを提供できるようになる。本画面は、新規配送プロファイルを作成するためのフォームを提供する。

**画面へのアクセス方法**：配送プロファイル一覧画面から「作成」ボタンをクリックしてアクセスする。URLパスは `/settings/locations/shipping-profiles/create` である。

**主要な操作・処理内容**：
1. 配送プロファイル名を入力する
2. 配送プロファイルのタイプを入力する
3. 保存して配送プロファイルを作成する
4. キャンセルして一覧画面に戻る

**画面遷移**：
- 遷移元: 配送プロファイル一覧画面
- 遷移先: 配送プロファイル詳細画面（作成成功時）、配送プロファイル一覧画面（キャンセル時）

**権限による表示制御**：管理者権限を持つユーザーのみアクセス可能。配送プロファイル作成権限がない場合は表示されない。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 44 | 配送プロファイル管理 | 主機能 | 新規配送プロファイルの作成 |

## 画面種別

登録（モーダル形式）

## URL/ルーティング

```
/settings/locations/shipping-profiles/create
```

## 入出力項目

### 入力項目

| 項目名 | 項目ID | データ型 | 必須 | バリデーション | 説明 |
|--------|--------|----------|------|----------------|------|
| 名前 | name | string | 必須 | 最小1文字 | 配送プロファイルの名称 |
| タイプ | type | string | 必須 | 最小1文字 | 配送プロファイルのタイプ |

## 表示項目

| 項目名 | 説明 |
|--------|------|
| ヘッダー | "配送プロファイルを作成"（shippingProfile.create.header） |
| 説明文 | 作成フォームの説明（shippingProfile.create.hint） |
| 名前フィールド | 入力フィールド（必須） |
| タイプフィールド | 入力フィールド（必須）、ツールチップあり |
| キャンセルボタン | モーダルを閉じる |
| 保存ボタン | 作成処理を実行 |

## イベント仕様

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

**トリガー**：保存ボタンをクリック、または Enter キー押下

**処理フロー**：
1. フォームのバリデーションを実行
2. バリデーションエラーがある場合はエラーメッセージを表示して処理を中断
3. `useCreateShippingProfile` フックを使用してAPIを呼び出し
4. 成功時: 成功トーストを表示し、作成された配送プロファイルの詳細画面へ遷移
5. 失敗時: エラートーストを表示

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

**トリガー**：キャンセルボタンをクリック

**処理フロー**：
1. モーダルを閉じる
2. 配送プロファイル一覧画面に戻る

### 3-入力フィールド変更

**トリガー**：名前またはタイプフィールドに入力

**処理フロー**：
1. react-hook-formによる状態更新
2. zodバリデーションによるリアルタイムバリデーション
3. エラーがある場合はフィールド下にエラーメッセージを表示

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| 保存ボタン押下 | shipping_profile | INSERT | 新規配送プロファイルを作成 |

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

#### shipping_profile

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| INSERT | id | 自動生成（UUID） | 主キー |
| INSERT | name | フォーム入力値 | 配送プロファイル名 |
| INSERT | type | フォーム入力値 | 配送プロファイルタイプ |
| INSERT | created_at | 現在日時 | 作成日時 |
| INSERT | updated_at | 現在日時 | 更新日時 |

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 | 表示条件 |
|-------------|------|---------------|----------|
| shippingProfile.create.successToast | 成功 | {name}を作成しました | 作成成功時 |
| - | エラー | {APIエラーメッセージ} | API呼び出し失敗時 |
| - | バリデーションエラー | 必須項目です | 必須フィールドが空の場合 |

## 例外処理

| 例外条件 | 処理内容 |
|---------|---------|
| バリデーションエラー | フィールド下にエラーメッセージを表示、フォーム送信を中断 |
| API呼び出し失敗 | エラートーストを表示し、モーダルは閉じない |
| ネットワークエラー | エラートーストを表示 |
| 重複名エラー | APIからのエラーメッセージをトーストで表示 |

## 備考

- RouteFocusModalコンポーネントを使用したモーダル形式
- KeyboundFormでキーボードショートカット（Enter送信等）をサポート
- zodとreact-hook-formによるフォームバリデーション
- 作成成功後は作成された配送プロファイルの詳細画面へ自動遷移

---

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

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

### 推奨読解順序

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

フォームのバリデーションスキーマを把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | create-shipping-profile-form.tsx | `packages/admin/dashboard/src/routes/shipping-profiles/shipping-profile-create/components/create-shipping-profile-form/create-shipping-profile-form.tsx` | CreateShippingOptionsSchemaの定義（15-18行目） |

**読解のコツ**: zodによるスキーマ定義は `name` と `type` の2フィールドのみで、両方とも最小1文字を要求。

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

画面のルートコンポーネントを特定する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | shipping-profile-create.tsx | `packages/admin/dashboard/src/routes/shipping-profiles/shipping-profile-create/shipping-profile-create.tsx` | ルートコンポーネント、RouteFocusModalでフォームをラップ |

**主要処理フロー**:
1. **4-10行目**: RouteFocusModalでCreateShippingProfileFormを表示

#### Step 3: フォームコンポーネントを理解する

作成フォームの実装を読み解く。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | create-shipping-profile-form.tsx | `packages/admin/dashboard/src/routes/shipping-profiles/shipping-profile-create/components/create-shipping-profile-form/create-shipping-profile-form.tsx` | フォーム全体の実装 |

**主要処理フロー**:
- **15-18行目**: zodによるバリデーションスキーマ定義
- **20-30行目**: useFormによるフォーム初期化、デフォルト値は空文字
- **32行目**: useCreateShippingProfileフックの取得
- **34-57行目**: handleSubmitで作成処理を実行
- **41-49行目**: 成功時のコールバック（トースト表示、詳細画面へ遷移）
- **50-52行目**: エラー時のコールバック（トースト表示）
- **59-129行目**: フォームUIのレンダリング

#### Step 4: APIフックを理解する

作成処理のAPIフック実装を読み解く。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | shipping-profiles.tsx | `packages/admin/dashboard/src/hooks/api/shipping-profiles.tsx` | useCreateShippingProfileの実装 |

**主要処理フロー**:
- **20-38行目**: useCreateShippingProfileでの作成処理
- **28行目**: sdk.admin.shippingProfile.createでAPIコール
- **29-32行目**: 成功時にクエリキャッシュを無効化

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

```
ShippingProfileCreate
    │
    └─ RouteFocusModal
           │
           └─ CreateShippingProfileForm
                  │
                  ├─ useForm (フォーム状態管理)
                  │      └─ zodResolver (バリデーション)
                  │
                  ├─ useCreateShippingProfile (作成処理)
                  │      └─ sdk.admin.shippingProfile.create
                  │
                  ├─ Form.Field (名前入力)
                  │
                  ├─ Form.Field (タイプ入力)
                  │
                  └─ KeyboundForm (キーボードサポート)
```

### データフロー図

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

フォーム入力                ───▶ useForm                        ───▶ フォーム状態
(name, type)                     (react-hook-form)

フォーム状態               ───▶ zodResolver                    ───▶ バリデーション結果
                                 (zodバリデーション)

バリデーション通過後       ───▶ useCreateShippingProfile       ───▶ shipping_profile
                                 (APIコール)

shipping_profile           ───▶ handleSuccess                  ───▶ 詳細画面へ遷移
                                 (リダイレクト)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| shipping-profile-create.tsx | `packages/admin/dashboard/src/routes/shipping-profiles/shipping-profile-create/` | ソース | ルートコンポーネント |
| create-shipping-profile-form.tsx | `packages/admin/dashboard/src/routes/shipping-profiles/shipping-profile-create/components/create-shipping-profile-form/` | ソース | 作成フォーム |
| shipping-profiles.tsx | `packages/admin/dashboard/src/hooks/api/` | ソース | APIフック |
| index.ts | `packages/admin/dashboard/src/routes/shipping-profiles/shipping-profile-create/` | ソース | エクスポート定義 |
| index.ts | `packages/admin/dashboard/src/routes/shipping-profiles/shipping-profile-create/components/create-shipping-profile-form/` | ソース | フォームコンポーネントのエクスポート |
