# 画面設計書 179-返品理由一覧画面

## 概要

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

### 本画面の処理概要

返品理由一覧画面は、システムに登録されている返品理由を一覧表示し、管理するための画面です。返品理由は顧客が返品を申請する際に選択できる理由として使用されます。

**業務上の目的・背景**：ECサイトにおける返品処理では、返品理由の記録が重要です。返品理由を標準化することで、返品データの分析、品質改善、カスタマーサポートの効率化が可能になります。また、返品理由は返品フロー（注文の返品作成画面）で顧客が選択するオプションとして表示されます。

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

**主要な操作・処理内容**：
1. 返品理由の一覧を確認（値、ラベル、説明等）
2. 検索機能で特定の返品理由を検索
3. 新規返品理由の作成（作成画面へ遷移）
4. 各返品理由の編集（編集画面へ遷移）
5. 各返品理由の削除（確認後に削除）

**画面遷移**：
- 遷移元：設定トップ画面
- 遷移先：返品理由作成画面、返品理由編集画面

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

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 14 | 返品理由管理 | 主機能 | 返品理由一覧の取得・表示 |

## 画面種別

一覧（SingleColumnPage形式）

## URL/ルーティング

`/settings/return-reasons`

## 入出力項目

| 項目名 | 項目ID | 種別 | 必須 | 最大長 | 説明 |
|--------|--------|------|------|--------|------|
| 検索クエリ | q | 入力（テキスト） | - | - | 値/ラベルによる検索 |

## 表示項目

### 一覧テーブル

| 項目名 | カラムID | 説明 |
|--------|----------|------|
| 値 | value | 返品理由の識別子（システム内部で使用） |
| ラベル | label | 顧客に表示される返品理由名 |
| 説明 | description | 返品理由の詳細説明 |
| アクション | - | 編集・削除メニュー |

## イベント仕様

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

返品理由作成画面（`/settings/return-reasons/create`）に遷移する。

### 2-アクションメニュー - 編集

返品理由編集画面（`/settings/return-reasons/{id}/edit`）に遷移する。

### 3-アクションメニュー - 削除

1. 確認ダイアログを表示
2. ユーザーが確認した場合、`useDeleteReturnReason`フックでAPI呼び出し
3. 成功時：トースト通知で成功メッセージを表示、一覧を再読み込み
4. エラー時：トースト通知でエラーメッセージを表示

### 4-検索入力

検索クエリに基づいて返品理由一覧をフィルタリングする。

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| 一覧表示 | return_reason | SELECT | 返品理由一覧の取得 |
| 削除 | return_reason | DELETE | 返品理由レコードの削除 |

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

#### return_reason（SELECT条件）

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | value, label | LIKE検索（qパラメータ） | 検索時 |

## メッセージ仕様

| 種別 | メッセージキー | 表示条件 |
|------|--------------|----------|
| ヘッダー | returnReasons.domain | ページタイトル |
| サブタイトル | returnReasons.subtitle | ページ説明文 |
| 確認 | general.areYouSure | 削除確認ダイアログ |
| 成功 | returnReasons.delete.successToast | 削除成功時 |
| エラー | (APIエラーメッセージ) | API呼び出し失敗時 |

## 例外処理

| 例外条件 | 処理内容 |
|----------|----------|
| API呼び出しエラー | エラーをスロー（ErrorBoundaryで捕捉） |
| ネットワークエラー | エラーをスロー |

## 備考

- ページネーション機能あり（1ページ20件）
- 検索機能あり
- 返品理由は階層構造を持つことが可能（parent_return_reason_id）

---

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

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

### 推奨読解順序

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

返品理由の型定義を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | validators.ts | `packages/medusa/src/api/admin/return-reasons/validators.ts` | L44-53: AdminCreateReturnReasonの型定義 |

**読解のコツ**: 返品理由のvalue/label/descriptionの役割を理解する。

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

一覧画面コンポーネントの構成を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | return-reason-list.tsx | `packages/admin/dashboard/src/routes/return-reasons/return-reason-list/return-reason-list.tsx` | L5-21: SingleColumnPageでテーブルを表示 |

**主要処理フロー**:
1. **L6**: useExtensionでウィジェット取得
2. **L8-20**: SingleColumnPageでReturnReasonListTableを表示

#### Step 3: テーブルコンポーネントを理解する

データ取得と表示処理を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | return-reason-list-table.tsx | `packages/admin/dashboard/src/routes/return-reasons/return-reason-list/components/return-reason-list-table/return-reason-list-table.tsx` | L20-128: データ取得と表示処理 |

**主要処理フロー**:
- **L22-24**: useReturnReasonTableQueryでクエリパラメータ取得
- **L26-31**: useReturnReasonsで返品理由一覧取得
- **L33**: useColumnsでカラム定義取得
- **L35-41**: useDataTableでテーブル構成
- **L56-58**: 作成ボタンの配置

#### Step 4: 行アクションを理解する

各行の編集・削除アクションを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | return-reason-list-table.tsx | `packages/admin/dashboard/src/routes/return-reasons/return-reason-list/components/return-reason-list-table/return-reason-list-table.tsx` | L79-109: ReturnReasonRowActionsコンポーネント |

**主要処理フロー**:
- **L83**: useDeleteReturnReasonActionで削除アクション取得
- **L88-107**: ActionMenuで編集・削除メニュー構成

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

```
ReturnReasonList (画面コンポーネント)
    │
    └─ ReturnReasonListTable (テーブルコンポーネント)
           │
           ├─ useReturnReasonTableQuery() (クエリパラメータ)
           │
           ├─ useReturnReasons() (返品理由一覧取得)
           │      └─ GET /admin/return-reasons
           │
           ├─ useReturnReasonTableColumns() (カラム定義)
           │
           ├─ _DataTable (テーブル表示)
           │
           └─ ReturnReasonRowActions (行アクション)
                  │
                  ├─ 編集リンク → /settings/return-reasons/{id}/edit
                  │
                  └─ useDeleteReturnReasonAction()
                         └─ DELETE /admin/return-reasons/{id}
```

### データフロー図

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

検索クエリ(q) ──────▶ useReturnReasonTableQuery
                            │
                            ▼
                   useReturnReasons(query)
                            │
                            ▼
              GET /admin/return-reasons?q=xxx
                            │
                            ▼
             return_reason テーブル ───▶ 一覧表示

[削除操作]           [処理]                    [結果]

削除ボタン ─────────▶ useDeleteReturnReasonAction
                            │
                            ▼
             DELETE /admin/return-reasons/{id}
                            │
                            ▼
              deleteReturnReasonsWorkflow ───▶ 一覧再取得
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| return-reason-list.tsx | `packages/admin/dashboard/src/routes/return-reasons/return-reason-list/return-reason-list.tsx` | ソース | 画面エントリーポイント |
| return-reason-list-table.tsx | `packages/admin/dashboard/src/routes/return-reasons/return-reason-list/components/return-reason-list-table/return-reason-list-table.tsx` | ソース | テーブルコンポーネント |
| use-delete-return-reason-action.tsx | `packages/admin/dashboard/src/routes/return-reasons/common/hooks/use-delete-return-reason-action.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バリデーション |
