# 画面設計書 181-返品理由編集画面

## 概要

本ドキュメントは、Medusa Admin Dashboard における返品理由編集画面の設計仕様を定義する。

### 本画面の処理概要

返品理由編集画面は、既存の返品理由の情報を編集するためのモーダル形式の画面である。

**業務上の目的・背景**：
EC運営において、返品理由のラベルや説明文を変更する必要が生じることがある。例えば、顧客からのフィードバックに基づき返品理由の表現をより分かりやすく変更したり、内部システムの識別子（value）を調整したりする場合に本画面を使用する。適切な返品理由の管理により、返品処理の効率化と顧客対応の品質向上を実現する。

**画面へのアクセス方法**：
設定画面 > 返品理由一覧画面 > 対象の返品理由の編集ボタン（鉛筆アイコン）をクリック、または返品理由一覧のアクションメニューから「編集」を選択することでアクセスする。

**主要な操作・処理内容**：
1. 返品理由の値（value）を入力/編集する - システム内部で使用される一意の識別子
2. 返品理由のラベル（label）を入力/編集する - 顧客や管理者に表示される名称
3. 返品理由の説明（description）を任意で入力/編集する - 返品理由の詳細説明
4. 保存ボタンを押下して変更を確定する

**画面遷移**：
- 遷移元：返品理由一覧画面
- 遷移先：保存完了後は返品理由一覧画面に戻る（ドロワーが閉じる）

**権限による表示制御**：
管理者権限を持つユーザーのみがアクセス可能。一般ユーザーはこの画面にアクセスできない。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 14 | 返品理由管理 | 主機能 | 返品理由の編集 |

## 画面種別

編集（モーダル/ドロワー形式）

## URL/ルーティング

`/settings/return-reasons/:id/edit`

## 入出力項目

| 項目名 | 項目ID | 型 | 必須 | 入力/出力 | バリデーション | 説明 |
|--------|--------|-----|------|-----------|----------------|------|
| 値 | value | string | 必須 | 入力 | 1文字以上 | システム識別子 |
| ラベル | label | string | 必須 | 入力 | 1文字以上 | 表示名称 |
| 説明 | description | string | 任意 | 入力 | なし | 詳細説明 |

## 表示項目

| 項目名 | 表示形式 | 説明 |
|--------|----------|------|
| ヘッダータイトル | テキスト | "Edit Return Reason" |
| 値フィールド | テキスト入力 | 現在の値が初期表示される |
| ラベルフィールド | テキスト入力 | 現在のラベルが初期表示される |
| 説明フィールド | テキストエリア | 現在の説明が初期表示される |
| キャンセルボタン | ボタン | 編集をキャンセル |
| 保存ボタン | ボタン | 変更を保存 |

## イベント仕様

### 1-画面初期表示

URLパラメータのIDを使用して返品理由データをAPIから取得し、フォームに初期値を設定する。データ取得中はローディング状態となる。

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

1. フォームバリデーションを実行
2. バリデーション成功時、`useUpdateReturnReason` フックを使用してAPIリクエストを送信
3. 成功時：成功トーストを表示し、ドロワーを閉じて一覧画面に戻る
4. 失敗時：エラートーストを表示

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

変更を破棄し、ドロワーを閉じて返品理由一覧画面に戻る。

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| 保存ボタン押下 | return_reason | UPDATE | 返品理由の更新 |

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

#### return_reason

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| UPDATE | value | フォーム入力値 | 一意識別子 |
| UPDATE | label | フォーム入力値 | 表示名称 |
| UPDATE | description | フォーム入力値（nullの場合あり） | 詳細説明 |
| UPDATE | updated_at | 現在日時 | 自動更新 |

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 | 表示条件 |
|-------------|------|---------------|----------|
| returnReasons.edit.successToast | 成功 | "Return reason {label} updated successfully" | 更新成功時 |
| - | エラー | APIエラーメッセージ | 更新失敗時 |

## 例外処理

| 例外ケース | 処理内容 |
|-----------|----------|
| 対象の返品理由が存在しない | エラーをスローし、エラーバウンダリでキャッチ |
| API通信エラー | エラートーストを表示 |
| バリデーションエラー | フォームフィールド下部にエラーメッセージを表示 |

## 備考

- 本画面はRouteDrawerコンポーネントを使用したドロワー形式で実装されている
- フォームはreact-hook-formとzodによるバリデーションを使用
- キーボードショートカット（Enter/Escape）に対応

---

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

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

### 推奨読解順序

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

まず、フォームで扱うデータ構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | return-reason-edit-form.tsx | `packages/admin/dashboard/src/routes/return-reasons/return-reason-edit/components/return-reason-edit-form/return-reason-edit-form.tsx` | 17-21行目: ReturnReasonEditSchemaでフォームのバリデーションスキーマを定義 |

**読解のコツ**: zodスキーマでvalue, label, descriptionの3フィールドを定義し、value/labelは必須、descriptionは任意となっている。

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

処理の起点となるファイルを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | return-reason-edit.tsx | `packages/admin/dashboard/src/routes/return-reasons/return-reason-edit/return-reason-edit.tsx` | コンポーネント全体の構造とデータ取得処理 |

**主要処理フロー**:
1. **9行目**: useParamsでURLからidを取得
2. **12行目**: useReturnReasonで返品理由データを取得
3. **14行目**: データ取得完了を判定
4. **20-31行目**: RouteDrawerでモーダルUIを構築し、データ準備完了後にReturnReasonEditFormを表示

#### Step 3: フォーム処理を理解する

フォームの実装詳細を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | return-reason-edit-form.tsx | `packages/admin/dashboard/src/routes/return-reasons/return-reason-edit/components/return-reason-edit-form/return-reason-edit-form.tsx` | フォームの実装とAPI連携 |

**主要処理フロー**:
- **29-36行目**: useFormでフォーム初期化、既存データをdefaultValuesに設定
- **38行目**: useUpdateReturnReasonで更新ミューテーションを取得
- **40-54行目**: handleSubmitで送信処理、成功時はトースト表示とモーダルクローズ
- **63-124行目**: Form.Fieldコンポーネントで各入力フィールドを構築

#### Step 4: API連携を理解する

APIフックの実装を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | return-reasons.tsx | `packages/admin/dashboard/src/hooks/api/return-reasons.tsx` | 返品理由関連のAPIフック |

**主要処理フロー**:
- **39-59行目**: useReturnReasonで詳細データを取得
- **81-104行目**: useUpdateReturnReasonで更新処理、成功時にキャッシュを無効化

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

```
ReturnReasonEdit (return-reason-edit.tsx)
    │
    ├─ useParams() - URLパラメータからID取得
    │
    ├─ useReturnReason(id) - 返品理由データ取得
    │      └─ sdk.admin.returnReason.retrieve()
    │
    └─ ReturnReasonEditForm
           │
           ├─ useForm() - フォーム状態管理
           │
           ├─ useUpdateReturnReason() - 更新ミューテーション
           │      └─ sdk.admin.returnReason.update()
           │
           └─ handleSubmit() - フォーム送信処理
```

### データフロー図

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

URLパラメータ ───▶ useReturnReason ───▶ フォーム初期値
    (id)              (API取得)

フォーム入力 ───▶ useUpdateReturnReason ───▶ 返品理由一覧更新
                     (API更新)              トースト通知
                                           ドロワークローズ
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| return-reason-edit.tsx | `packages/admin/dashboard/src/routes/return-reasons/return-reason-edit/return-reason-edit.tsx` | ソース | 編集画面のメインコンポーネント |
| return-reason-edit-form.tsx | `packages/admin/dashboard/src/routes/return-reasons/return-reason-edit/components/return-reason-edit-form/return-reason-edit-form.tsx` | ソース | 編集フォームコンポーネント |
| return-reasons.tsx | `packages/admin/dashboard/src/hooks/api/return-reasons.tsx` | ソース | 返品理由APIフック |
| RouteDrawer | `packages/admin/dashboard/src/components/modals` | ソース | ドロワーモーダルコンポーネント |
| Form | `packages/admin/dashboard/src/components/common/form` | ソース | フォームコンポーネント |
