# 画面設計書 182-返金理由一覧画面

## 概要

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

### 本画面の処理概要

返金理由一覧画面は、システムに登録されているすべての返金理由を一覧表示し、返金理由の管理（作成・編集・削除）を行うための画面である。

**業務上の目的・背景**：
EC運営において、返金処理を行う際に返金理由を記録することは、業務分析や顧客対応の品質向上に不可欠である。本画面では、返金理由のマスタデータを一元管理し、返金処理時に選択可能な理由を適切に維持することで、返金業務の標準化と効率化を実現する。また、返金理由の追加・変更・削除を通じて、事業運営の変化に柔軟に対応できる。

**画面へのアクセス方法**：
設定画面 > 「返金理由」メニューをクリックすることでアクセスする。URLに直接アクセスすることも可能。

**主要な操作・処理内容**：
1. 返金理由一覧の閲覧 - 登録されている返金理由をテーブル形式で表示
2. 返金理由の検索 - 検索機能で特定の返金理由を絞り込み
3. 返金理由の新規作成 - 「作成」ボタンで新規作成画面へ遷移
4. 返金理由の編集 - アクションメニューから編集画面へ遷移
5. 返金理由の削除 - アクションメニューから削除を実行（確認ダイアログあり）

**画面遷移**：
- 遷移元：設定画面
- 遷移先：返金理由作成画面、返金理由編集画面

**権限による表示制御**：
管理者権限を持つユーザーのみがアクセス可能。

## 関連機能

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

## 画面種別

一覧

## URL/ルーティング

`/settings/refund-reasons`

## 入出力項目

本画面は一覧表示が主目的のため、入力項目は検索フィールドのみ。

| 項目名 | 項目ID | 型 | 必須 | 入力/出力 | バリデーション | 説明 |
|--------|--------|-----|------|-----------|----------------|------|
| 検索 | search | string | 任意 | 入力 | なし | 返金理由の検索キーワード |

## 表示項目

| 項目名 | 表示形式 | 説明 |
|--------|----------|------|
| タイトル | テキスト | "Refund Reasons" |
| サブタイトル | テキスト | 返金理由の説明文 |
| 作成ボタン | ボタン | 新規作成画面への遷移 |
| 検索フィールド | テキスト入力 | キーワード検索 |
| 返金理由テーブル | DataTable | 返金理由の一覧 |
| ページネーション | コンポーネント | ページ切り替え |

### テーブルカラム

| カラム名 | 説明 |
|---------|------|
| ラベル | 返金理由の表示名 |
| コード | 返金理由のコード（識別子） |
| 説明 | 返金理由の説明 |
| アクション | 編集・削除メニュー |

## イベント仕様

### 1-画面初期表示

`useRefundReasons` フックを使用してAPIから返金理由一覧を取得し、DataTableに表示する。

### 2-検索実行

検索キーワードに基づいてフィルタリングされた返金理由一覧を表示する。

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

`/settings/refund-reasons/create` へ遷移し、返金理由作成画面を表示する。

### 4-編集アクション選択

1. アクションメニューから「編集」を選択
2. `/settings/refund-reasons/:id/edit` へ遷移
3. 返金理由編集画面を表示

### 5-削除アクション選択

1. アクションメニューから「削除」を選択
2. 確認ダイアログを表示
3. 確認後、`useDeleteRefundReasonLazy` を使用して削除APIを呼び出し
4. 成功時：成功トーストを表示し、一覧を更新
5. 失敗時：エラートーストを表示

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| 画面初期表示 | refund_reason | SELECT | 返金理由一覧の取得 |
| 削除アクション | refund_reason | DELETE | 返金理由の削除 |

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

#### refund_reason（削除時）

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| DELETE | - | WHERE id = 選択した返金理由ID | 物理削除 |

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 | 表示条件 |
|-------------|------|---------------|----------|
| general.areYouSure | 確認 | "Are you sure?" | 削除確認ダイアログ |
| refundReasons.delete.confirmation | 確認 | "Are you sure you want to delete {label}?" | 削除確認ダイアログ |
| refundReasons.delete.successToast | 成功 | 削除成功メッセージ | 削除成功時 |
| general.noRecordsMessage | 情報 | レコードなしメッセージ | データが存在しない場合 |
| general.noRecordsMessageFiltered | 情報 | フィルタ結果なしメッセージ | 検索結果が0件の場合 |

## 例外処理

| 例外ケース | 処理内容 |
|-----------|----------|
| API通信エラー（一覧取得） | エラーをスローし、エラーバウンダリでキャッチ |
| API通信エラー（削除） | エラートーストを表示 |
| データが存在しない | 空状態のメッセージを表示 |

## 備考

- ページサイズは20件固定
- SingleColumnPageレイアウトを使用
- 拡張ウィジェット機能に対応（refund_reason.list.before/after）
- keepPreviousDataオプションでページ遷移時のちらつきを防止

---

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

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

### 推奨読解順序

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

まず、APIレスポンスの構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | refund-reasons.tsx | `packages/admin/dashboard/src/hooks/api/refund-reasons.tsx` | HttpTypes.AdminRefundReasonの構造を確認 |

**読解のコツ**: AdminRefundReasonはid, label, code, descriptionなどのフィールドを持つ。

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

画面のメインコンポーネントを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | refund-reason-list.tsx | `packages/admin/dashboard/src/routes/refund-reasons/refund-reason-list/refund-reason-list.tsx` | ページ構造とレイアウト |

**主要処理フロー**:
1. **6行目**: useExtensionでウィジェット機能を取得
2. **8-19行目**: SingleColumnPageでページレイアウトを構築
3. **18行目**: RefundReasonListTableコンポーネントを配置

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

一覧表示の実装詳細を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | refund-reason-list-table.tsx | `packages/admin/dashboard/src/routes/refund-reasons/refund-reason-list/components/refund-reason-list-table/refund-reason-list-table.tsx` | テーブル表示とアクション処理 |

**主要処理フロー**:
- **21行目**: PAGE_SIZE = 20の定義
- **25-27行目**: useRefundReasonTableQueryで検索パラメータを管理
- **29-34行目**: useRefundReasonsでデータ取得（keepPreviousData使用）
- **36行目**: useColumnsでテーブルカラムを構築
- **42-71行目**: DataTableコンポーネントで一覧表示
- **84-109行目**: handleDeleteで削除処理（確認ダイアログ + API呼び出し）
- **111-138行目**: カラム定義（baseカラム + アクションカラム）

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

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

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

**主要処理フロー**:
- **17-35行目**: useRefundReasonsで一覧取得
- **103-124行目**: useDeleteRefundReasonLazyで遅延削除（IDを引数で受け取る）

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

```
RefundReasonList (refund-reason-list.tsx)
    │
    └─ RefundReasonListTable
           │
           ├─ useRefundReasonTableQuery() - 検索パラメータ管理
           │
           ├─ useRefundReasons() - 一覧データ取得
           │      └─ sdk.admin.refundReason.list()
           │
           ├─ useColumns() - カラム定義
           │      │
           │      ├─ useRefundReasonTableColumns() - 基本カラム
           │      │
           │      └─ useDeleteRefundReasonLazy() - 削除処理
           │             └─ sdk.admin.refundReason.delete()
           │
           └─ DataTable - テーブル表示
```

### データフロー図

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

検索パラメータ ───▶ useRefundReasons ───▶ テーブル表示
                     (API取得)

削除ボタン ───▶ 確認ダイアログ ───▶ useDeleteRefundReasonLazy ───▶ 一覧更新
                                      (API削除)                    トースト通知
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| refund-reason-list.tsx | `packages/admin/dashboard/src/routes/refund-reasons/refund-reason-list/refund-reason-list.tsx` | ソース | 一覧画面のメインコンポーネント |
| refund-reason-list-table.tsx | `packages/admin/dashboard/src/routes/refund-reasons/refund-reason-list/components/refund-reason-list-table/refund-reason-list-table.tsx` | ソース | テーブルコンポーネント |
| refund-reasons.tsx | `packages/admin/dashboard/src/hooks/api/refund-reasons.tsx` | ソース | 返金理由APIフック |
| loader.ts | `packages/admin/dashboard/src/routes/refund-reasons/refund-reason-list/loader.ts` | ソース | ルートローダー |
| SingleColumnPage | `packages/admin/dashboard/src/components/layout/pages` | ソース | ページレイアウトコンポーネント |
| DataTable | `packages/admin/dashboard/src/components/data-table` | ソース | テーブルコンポーネント |
