# 画面設計書 180-返品理由作成画面

## 概要

本ドキュメントは、Medusa Admin Dashboard における返品理由作成画面の設計を記述したものです。

### 本画面の処理概要

返品理由作成画面は、新しい返品理由を登録するためのモーダル画面です。返品理由は顧客が返品を申請する際に選択可能なオプションとして使用されます。

**業務上の目的・背景**：ECサイトの返品処理において、返品理由は重要な情報です。適切な返品理由を用意することで、返品データの分析、製品品質の改善、カスタマーサポートの効率化が可能になります。返品理由には「値（システム内部識別子）」と「ラベル（顧客向け表示名）」があり、多言語対応やシステム連携に対応できる設計になっています。

**画面へのアクセス方法**：設定メニュー > 返品理由一覧画面 > 「作成」ボタンをクリックしてアクセスします。URLは `/settings/return-reasons/create` です。

**主要な操作・処理内容**：
1. 返品理由の値（value）を入力（システム内部で使用される識別子）
2. 返品理由のラベル（label）を入力（顧客に表示される名前）
3. 説明（description）を入力（オプション）
4. 「保存」ボタンをクリックして返品理由を作成する

**画面遷移**：
- 遷移元：返品理由一覧画面（「作成」ボタン押下）
- 遷移先：返品理由一覧画面（作成成功時/キャンセル時）

**権限による表示制御**：認証済みの管理者のみがアクセス可能です。

## 関連機能

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

## 画面種別

登録（モーダル形式）

## URL/ルーティング

`/settings/return-reasons/create`

## 入出力項目

| 項目名 | 項目ID | 種別 | 必須 | 最大長 | 説明 |
|--------|--------|------|------|--------|------|
| 値 | value | 入力（テキスト） | ○ | - | システム内部で使用される識別子 |
| ラベル | label | 入力（テキスト） | ○ | - | 顧客に表示される返品理由名 |
| 説明 | description | 入力（テキストエリア） | - | - | 返品理由の詳細説明 |

## 表示項目

| 項目名 | 説明 |
|--------|------|
| ヘッダータイトル | "Create Return Reason" |
| 説明文 | 返品理由作成の説明テキスト |
| 値のツールチップ | 値フィールドの説明 |

## イベント仕様

### 1-フォーム送信（保存ボタン押下）

1. フォームバリデーションを実行
   - 値（value）が空の場合はエラー表示
   - ラベル（label）が空の場合はエラー表示
2. `useCreateReturnReason` フックを使用してAPIを呼び出し
3. 成功時：
   - トースト通知で成功メッセージを表示
   - モーダルを閉じて返品理由一覧画面に戻る
4. エラー時：
   - トースト通知でエラーメッセージを表示

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

モーダルを閉じ、返品理由一覧画面に戻る。

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

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

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

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

#### return_reason

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| INSERT | id | 自動生成（UUID） | プライマリキー |
| INSERT | value | フォーム入力値 | システム識別子 |
| INSERT | label | フォーム入力値 | 表示名 |
| INSERT | description | フォーム入力値 | 説明（オプション） |
| INSERT | parent_return_reason_id | null | 親理由ID（将来的な階層構造用） |
| INSERT | created_at | 現在日時 | 作成日時 |

## メッセージ仕様

| 種別 | メッセージキー | 表示条件 |
|------|--------------|----------|
| 成功 | returnReasons.create.successToast | 返品理由作成成功時 |
| エラー | (APIエラーメッセージ) | API呼び出し失敗時 |
| ツールチップ | returnReasons.fields.value.tooltip | 値フィールドにホバー時 |
| プレースホルダー | returnReasons.fields.value.placeholder | 値フィールド |
| プレースホルダー | returnReasons.fields.label.placeholder | ラベルフィールド |
| プレースホルダー | returnReasons.fields.description.placeholder | 説明フィールド |

## 例外処理

| 例外条件 | 処理内容 |
|----------|----------|
| 値（value）未入力 | フォームバリデーションエラー表示 |
| ラベル（label）未入力 | フォームバリデーションエラー表示 |
| API呼び出しエラー | トースト通知でエラーメッセージ表示 |
| 重複する値（value）| APIエラーメッセージ表示 |

## 備考

- 値（value）は一意である必要がある（システム識別子のため）
- 説明（description）はオプショナル
- 将来的に親返品理由を設定できる階層構造に対応

---

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

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

### 推奨読解順序

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

フォームスキーマと型定義を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | return-reason-create-form.tsx | `packages/admin/dashboard/src/routes/return-reasons/return-reason-create/components/return-reason-create-form/return-reason-create-form.tsx` | L14-18: Zodスキーマで必須項目を定義 |
| 1-2 | validators.ts | `packages/medusa/src/api/admin/return-reasons/validators.ts` | L44-53: AdminCreateReturnReasonの型定義 |

**読解のコツ**: valueとlabelの違いと、それぞれの用途を理解する。

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

モーダルコンポーネントの構成を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | return-reason-create.tsx | `packages/admin/dashboard/src/routes/return-reasons/return-reason-create/return-reason-create.tsx` | L4-10: RouteFocusModalでフォーム表示 |

**主要処理フロー**:
1. **L6-8**: RouteFocusModalでReturnReasonCreateFormをラップ

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

フォームの表示とサブミット処理を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | return-reason-create-form.tsx | `packages/admin/dashboard/src/routes/return-reasons/return-reason-create/components/return-reason-create-form/return-reason-create-form.tsx` | L20-157: フォーム処理全体 |

**主要処理フロー**:
- **L24-31**: useFormでフォーム初期化
- **L33**: useCreateReturnReasonでミューテーションフック取得
- **L35-49**: handleSubmitでAPI呼び出しと成功/エラー処理
- **L70-117**: 2カラムレイアウトで値とラベルのフィールド配置
- **L118-139**: 説明フィールド（Textarea）

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

バックエンドとの通信処理を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | return-reasons.tsx | `packages/admin/dashboard/src/hooks/api/return-reasons.tsx` | L61-80: useCreateReturnReasonフック |

**主要処理フロー**:
- **L70**: `sdk.admin.returnReason.create(data)`でAPI呼び出し
- **L71-74**: 成功時にreturnReasonsのリストキャッシュを無効化

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

```
ReturnReasonCreate (画面コンポーネント)
    │
    └─ ReturnReasonCreateForm (フォームコンポーネント)
           │
           ├─ useForm() (フォーム状態管理)
           │
           ├─ useCreateReturnReason() (API呼び出しフック)
           │      └─ sdk.admin.returnReason.create()
           │             └─ POST /admin/return-reasons
           │                    └─ createReturnReasonsWorkflow
           │
           └─ handleSuccess("../") (一覧画面に戻る)
```

### データフロー図

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

value ──────────────┐
                    │
label ──────────────┤
                    ├──▶ useForm ───────▶ バリデーション
description ────────┘        │
                             ▼
                    useCreateReturnReason
                             │
                             ▼
                  POST /admin/return-reasons
                             │
                             ▼
               createReturnReasonsWorkflow
                             │
                             ▼
              return_reasonレコード作成 ───▶ 一覧画面へ遷移
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| return-reason-create.tsx | `packages/admin/dashboard/src/routes/return-reasons/return-reason-create/return-reason-create.tsx` | ソース | 画面エントリーポイント |
| return-reason-create-form.tsx | `packages/admin/dashboard/src/routes/return-reasons/return-reason-create/components/return-reason-create-form/return-reason-create-form.tsx` | ソース | フォームコンポーネント |
| return-reasons.tsx | `packages/admin/dashboard/src/hooks/api/return-reasons.tsx` | ソース | APIフック |
| route.ts | `packages/medusa/src/api/admin/return-reasons/route.ts` | ソース | バックエンドAPIルート |
| validators.ts | `packages/medusa/src/api/admin/return-reasons/validators.ts` | ソース | APIバリデーション |
