# 画面設計書 147-配送オプションタイプ作成画面

## 概要

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

### 本画面の処理概要

**業務上の目的・背景**：配送オプションタイプは配送オプションを分類するための識別子である。新しい配送方法のカテゴリ（例：「当日配送」「コンビニ受取」など）を追加する場合、管理者は新しい配送オプションタイプを作成する。本画面は、ラベル、コード、説明を入力して新規配送オプションタイプを作成するためのフォームを提供する。

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

**主要な操作・処理内容**：
1. 配送オプションタイプのラベルを入力する
2. 配送オプションタイプのコードを入力する（ラベルから自動生成も可）
3. 配送オプションタイプの説明を入力する（任意）
4. 保存して配送オプションタイプを作成する
5. キャンセルして一覧画面に戻る

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

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

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 43 | 配送オプション管理 | 主機能 | 新規配送オプションタイプの作成 |

## 画面種別

登録（モーダル形式）

## URL/ルーティング

```
/settings/locations/shipping-option-types/create
```

## 入出力項目

### 入力項目

| 項目名 | 項目ID | データ型 | 必須 | バリデーション | 説明 |
|--------|--------|----------|------|----------------|------|
| ラベル | label | string | 必須 | 最小1文字 | 配送オプションタイプの表示名 |
| コード | code | string | 必須 | 最小1文字 | 配送オプションタイプの識別コード |
| 説明 | description | string | - | なし | 配送オプションタイプの説明 |

## 表示項目

| 項目名 | 説明 |
|--------|------|
| ヘッダー | "配送オプションタイプを作成"（shippingOptionTypes.create.header） |
| 説明文 | 作成フォームの説明（shippingOptionTypes.create.hint） |
| ラベルフィールド | 入力フィールド（必須） |
| コードフィールド | 入力フィールド（必須）、ラベルから自動生成 |
| 説明フィールド | 入力フィールド（任意） |
| キャンセルボタン | モーダルを閉じる |
| 作成ボタン | 作成処理を実行 |

## イベント仕様

### 1-作成ボタン押下

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

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

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

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

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

### 3-ラベルフィールド変更

**トリガー**：ラベルフィールドに入力

**処理フロー**：
1. react-hook-formによる状態更新
2. コードフィールドが未入力または未タッチの場合、ラベルからコードを自動生成
3. 自動生成ロジック：小文字に変換、英数字以外をアンダースコアに置換、連続アンダースコアを単一化、先頭・末尾のアンダースコアを除去

### 4-コードフィールド変更

**トリガー**：コードフィールドに入力

**処理フロー**：
1. react-hook-formによる状態更新
2. ラベルからの自動生成を停止（フィールドがタッチされたとマーク）

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| 作成ボタン押下 | shipping_option_type | INSERT | 新規配送オプションタイプを作成 |

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

#### shipping_option_type

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| INSERT | id | 自動生成（UUID） | 主キー |
| INSERT | label | フォーム入力値 | 配送オプションタイプの表示名 |
| INSERT | code | フォーム入力値 | 配送オプションタイプのコード |
| INSERT | description | フォーム入力値（任意） | 説明 |
| INSERT | created_at | 現在日時 | 作成日時 |
| INSERT | updated_at | 現在日時 | 更新日時 |

## メッセージ仕様

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

## 例外処理

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

## 備考

- RouteFocusModalコンポーネントを使用したモーダル形式
- KeyboundFormでキーボードショートカット（Enter送信等）をサポート
- zodとreact-hook-formによるフォームバリデーション
- ラベル入力時にコードを自動生成する機能あり（`generateCodeFromLabel`関数）
- 作成成功後は作成された配送オプションタイプの詳細画面へ自動遷移

---

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

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

### 推奨読解順序

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

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

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

**読解のコツ**: zodによるスキーマ定義は `label`（必須）、`code`（必須）、`description`（任意）の3フィールド。

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

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

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

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

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

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

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

**主要処理フロー**:
- **11-15行目**: zodによるバリデーションスキーマ定義
- **21-28行目**: useFormによるフォーム初期化
- **30-36行目**: generateCodeFromLabel関数（ラベルからコード自動生成）
- **38行目**: useCreateShippingOptionTypeフックの取得
- **40-58行目**: handleSubmitで作成処理を実行
- **43-52行目**: 成功時のコールバック（トースト表示、詳細画面へ遷移）
- **53-55行目**: エラー時のコールバック（トースト表示）
- **73-102行目**: labelフィールド（onChange時にコード自動生成）
- **104-120行目**: codeフィールド
- **121-144行目**: descriptionフィールド（任意、optionalラベル付き）

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

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

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

**主要処理フロー**:
- **62-80行目**: useCreateShippingOptionTypeでの作成処理
- **70行目**: sdk.admin.shippingOptionType.createでAPIコール
- **71-74行目**: 成功時にクエリキャッシュを無効化

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

```
ShippingOptionTypeCreate
    │
    └─ RouteFocusModal
           │
           └─ CreateShippingOptionTypeForm
                  │
                  ├─ useForm (フォーム状態管理)
                  │      └─ zodResolver (バリデーション)
                  │
                  ├─ generateCodeFromLabel (コード自動生成)
                  │
                  ├─ useCreateShippingOptionType (作成処理)
                  │      └─ sdk.admin.shippingOptionType.create
                  │
                  ├─ Form.Field (ラベル入力)
                  │
                  ├─ Form.Field (コード入力)
                  │
                  ├─ Form.Field (説明入力)
                  │
                  └─ KeyboundForm (キーボードサポート)
```

### データフロー図

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

ラベル入力                 ───▶ generateCodeFromLabel          ───▶ コード自動生成
                                (変換ロジック)

フォーム入力               ───▶ useForm                        ───▶ フォーム状態
(label, code, description)      (react-hook-form)

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

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

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

### 関連ファイル一覧

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