# 画面設計書 149-配送オプションタイプ編集画面

## 概要

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

### 本画面の処理概要

**業務上の目的・背景**：配送オプションタイプの情報を更新する必要がある場合（表示名の変更、コードの修正、説明の追加など）、管理者は本画面を使用して既存の配送オプションタイプを編集する。本画面は、ラベル、コード、説明を編集するためのフォームを提供する。

**画面へのアクセス方法**：配送オプションタイプ詳細画面のアクションメニューから「編集」を選択してアクセスする。URLパスは `/settings/locations/shipping-option-types/:id/edit` である。

**主要な操作・処理内容**：
1. 配送オプションタイプの現在の情報を表示する
2. ラベルを編集する
3. コードを編集する
4. 説明を編集する（任意）
5. 保存して変更を反映する
6. キャンセルして詳細画面に戻る

**画面遷移**：
- 遷移元: 配送オプションタイプ詳細画面
- 遷移先: 配送オプションタイプ詳細画面（保存・キャンセル後）

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

## 関連機能

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

## 画面種別

編集（ドロワー形式）

## URL/ルーティング

```
/settings/locations/shipping-option-types/:id/edit
```

## 入出力項目

### URLパラメータ

| 項目名 | 項目ID | データ型 | 必須 | 説明 |
|--------|--------|----------|------|------|
| 配送オプションタイプID | id | string | 必須 | 編集対象の配送オプションタイプID |

### 入力項目

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

## 表示項目

| 項目名 | 説明 |
|--------|------|
| ヘッダー | "配送オプションタイプを編集"（shippingOptionTypes.edit.header） |
| ラベルフィールド | 入力フィールド（必須）、現在値がプリセット |
| コードフィールド | 入力フィールド（必須）、現在値がプリセット |
| 説明フィールド | 入力フィールド（任意）、現在値がプリセット |
| キャンセルボタン | ドロワーを閉じる |
| 保存ボタン | 更新処理を実行 |

## イベント仕様

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

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

**処理フロー**：
1. フォームのバリデーションを実行
2. バリデーションエラーがある場合はエラーメッセージを表示して処理を中断
3. `useUpdateShippingOptionType` フックを使用してAPIを呼び出し
4. 成功時: 成功トーストを表示し、ドロワーを閉じて詳細画面に戻る
5. 失敗時: エラートーストを表示

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

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

**処理フロー**：
1. ドロワーを閉じる
2. 配送オプションタイプ詳細画面に戻る

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

**トリガー**：ラベル、コード、説明フィールドに入力

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

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

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

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

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

#### shipping_option_type

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

## メッセージ仕様

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

## 例外処理

| 例外条件 | 処理内容 |
|---------|---------|
| 配送オプションタイプ取得失敗 | エラーをthrowし、エラーページを表示 |
| バリデーションエラー | フィールド下にエラーメッセージを表示、フォーム送信を中断 |
| API呼び出し失敗 | エラートーストを表示し、ドロワーは閉じない |
| ネットワークエラー | エラートーストを表示 |

## 備考

- RouteDrawerコンポーネントを使用したドロワー（サイドパネル）形式
- KeyboundFormでキーボードショートカット（Enter送信等）をサポート
- zodとreact-hook-formによるフォームバリデーション
- 現在の値がフォームにプリセットされる
- 作成画面と異なり、ラベルからコードの自動生成機能はない

---

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

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

### 推奨読解順序

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

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

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

**読解のコツ**: zodによるスキーマ定義は作成画面と同じ構造（`label`, `code`, `description`）。

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

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

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

**主要処理フロー**:
1. **9行目**: useParamsでidを取得
2. **10行目**: useTranslationで国際化対応
3. **12-13行目**: useShippingOptionTypeでデータ取得
4. **15行目**: データ取得完了の判定
5. **17-19行目**: エラー時はerrorをthrow
6. **21-29行目**: RouteDrawerでEditShippingOptionTypeFormを表示

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

編集フォームの実装を読み解く。

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

**主要処理フロー**:
- **12-16行目**: zodによるバリデーションスキーマ定義
- **28-35行目**: useFormによるフォーム初期化（現在値をdefaultValuesに設定）
- **37-39行目**: useUpdateShippingOptionTypeフックの取得
- **41-62行目**: handleSubmitで更新処理を実行
- **49-54行目**: 成功時のコールバック（トースト表示、ドロワーを閉じる）
- **55-57行目**: エラー時のコールバック（トースト表示）
- **64-145行目**: フォームUIのレンダリング

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

更新処理のAPIフック実装を読み解く。

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

**主要処理フロー**:
- **82-104行目**: useUpdateShippingOptionTypeでの更新処理
- **91行目**: sdk.admin.shippingOptionType.updateでAPIコール
- **92-99行目**: 成功時にクエリキャッシュを無効化

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

```
ShippingOptionTypeEdit
    │
    ├─ useParams (URLパラメータ取得)
    │
    ├─ useShippingOptionType (データ取得)
    │      └─ sdk.admin.shippingOptionType.retrieve
    │
    └─ RouteDrawer
           │
           └─ EditShippingOptionTypeForm
                  │
                  ├─ useForm (フォーム状態管理)
                  │      └─ zodResolver (バリデーション)
                  │
                  ├─ useUpdateShippingOptionType (更新処理)
                  │      └─ sdk.admin.shippingOptionType.update
                  │
                  ├─ Form.Field (ラベル入力)
                  │
                  ├─ Form.Field (コード入力)
                  │
                  ├─ Form.Field (説明入力)
                  │
                  └─ KeyboundForm (キーボードサポート)
```

### データフロー図

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

URLパラメータ              ───▶ useParams                       ───▶ id
(id)

id                         ───▶ useShippingOptionType           ───▶ shipping_option_type
                                (APIコール)                          (現在値)

shipping_option_type       ───▶ useForm                         ───▶ フォーム状態
                                (defaultValuesに設定)

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

バリデーション通過後       ───▶ useUpdateShippingOptionType     ───▶ 更新結果
                                (APIコール)

更新結果                   ───▶ handleSuccess                   ───▶ ドロワーを閉じる
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| shipping-option-type-edit.tsx | `packages/admin/dashboard/src/routes/shipping-option-types/shipping-option-type-edit/` | ソース | ルートコンポーネント |
| edit-shipping-option-type-form.tsx | `packages/admin/dashboard/src/routes/shipping-option-types/shipping-option-type-edit/components/edit-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-edit/` | ソース | エクスポート定義 |
