# 画面設計書 146-配送オプションタイプ一覧画面

## 概要

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

### 本画面の処理概要

**業務上の目的・背景**：配送オプションタイプは、配送オプションを分類・識別するための概念である。例えば「標準配送」「速達配送」「店舗受取」など、配送方法の種類をコード値とラベルのペアで管理する。本画面では、システムに登録されているすべての配送オプションタイプを一覧表示し、管理者が効率的に配送オプションタイプを確認・管理できるようにする。

**画面へのアクセス方法**：設定 > ロケーション > 配送オプションタイプ の順にナビゲートしてアクセスする。URLパスは `/settings/locations/shipping-option-types` である。

**主要な操作・処理内容**：
1. 配送オプションタイプの一覧を表示する
2. ラベル、コード、説明でフィルタ・検索する
3. 並び替え（ラベル、コード、説明、作成日、更新日）を行う
4. 新規配送オプションタイプ作成画面へ遷移する
5. 配送オプションタイプ詳細画面へ遷移する
6. 配送オプションタイプを削除する

**画面遷移**：
- 遷移元: 設定画面、ロケーション一覧画面
- 遷移先: 配送オプションタイプ作成画面、配送オプションタイプ詳細画面

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

## 関連機能

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

## 画面種別

一覧

## URL/ルーティング

```
/settings/locations/shipping-option-types
```

## 入出力項目

### 入力項目（検索・フィルタ）

| 項目名 | 項目ID | データ型 | 必須 | 説明 |
|--------|--------|----------|------|------|
| 検索キーワード | q | string | - | ラベル、コードでの検索 |
| ページサイズ | limit | number | - | 1ページあたりの表示件数（デフォルト: 20） |
| オフセット | offset | number | - | ページネーションのオフセット |
| 並び替えキー | order | string | - | 並び替えに使用するフィールド |

## 表示項目

### テーブル列定義

| 項目名 | データソース | 説明 |
|--------|-------------|------|
| ラベル | shipping_option_type.label | 配送オプションタイプの表示名 |
| コード | shipping_option_type.code | 配送オプションタイプの識別コード |
| 説明 | shipping_option_type.description | 配送オプションタイプの説明 |
| アクション | - | 編集・削除などの操作メニュー |

### ヘッダー部

| 項目名 | 説明 |
|--------|------|
| タイトル | "配送オプションタイプ"（shippingOptionTypes.domain） |
| サブタイトル | 配送オプションタイプの説明文（shippingOptionTypes.subtitle） |
| 作成ボタン | 新規配送オプションタイプ作成画面へのリンク |

### フッター部

| 項目名 | 説明 |
|--------|------|
| ページネーション | 前へ/次へ、ページ番号表示 |
| 件数表示 | 総件数の表示 |

## イベント仕様

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

**トリガー**：「作成」ボタンをクリック

**処理フロー**：
1. `/settings/locations/shipping-option-types/create` へ遷移
2. 配送オプションタイプ作成モーダルを表示

### 2-行クリック

**トリガー**：テーブルの行をクリック

**処理フロー**：
1. クリックされた行のIDを取得
2. `/settings/locations/shipping-option-types/:id` へ遷移
3. 配送オプションタイプ詳細画面を表示

### 3-編集アクション

**トリガー**：行のアクションメニューから「編集」を選択

**処理フロー**：
1. `/settings/locations/shipping-option-types/:id/edit` へ遷移
2. 配送オプションタイプ編集モーダルを表示

### 4-削除アクション

**トリガー**：行のアクションメニューから「削除」を選択

**処理フロー**：
1. 確認プロンプトを表示
2. ユーザーが確認した場合、`useDeleteShippingOptionType` フックを使用してAPIを呼び出し
3. 成功時: 成功トーストを表示し、一覧を更新
4. 失敗時: エラートーストを表示

### 5-検索実行

**トリガー**：検索フィールドに入力後、Enter または 検索アイコンをクリック

**処理フロー**：
1. 検索キーワードをクエリパラメータに設定
2. `useShippingOptionTypes` フックで検索結果を取得
3. テーブルを更新

### 6-並び替え

**トリガー**：並び替えセレクタで項目を選択

**処理フロー**：
1. 選択された並び替えキー（label, code, description, created_at, updated_at）をクエリパラメータに設定
2. `useShippingOptionTypes` フックで並び替え結果を取得
3. テーブルを更新

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| 削除アクション | shipping_option_type | DELETE | 配送オプションタイプを削除 |

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

#### shipping_option_type

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| DELETE | id | 選択された配送オプションタイプのID | 物理削除またはソフトデリート |

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 | 表示条件 |
|-------------|------|---------------|----------|
| shippingOptionTypes.delete.title | 確認 | 削除確認 | 削除アクション選択時 |
| shippingOptionTypes.delete.successToast | 成功 | {label}を削除しました | 削除成功時 |
| - | エラー | {APIエラーメッセージ} | API呼び出し失敗時 |

## 例外処理

| 例外条件 | 処理内容 |
|---------|---------|
| 配送オプションタイプ一覧取得失敗 | エラーをthrowし、エラーページを表示 |
| 削除処理失敗 | エラートーストを表示し、一覧は更新しない |
| ネットワークエラー | エラートーストを表示 |

## 備考

- `keepPreviousData` オプションにより、ページネーション時にちらつきを防止
- SingleColumnPageレイアウトを使用
- 拡張ウィジェット（before/after）をサポート
- PAGE_SIZE は 20 件固定
- useShippingOptionTypeTableColumnsフックで共通の列定義を使用

---

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

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

### 推奨読解順序

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

配送オプションタイプのデータ構造を把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | HttpTypes | `packages/core/types/src/http/fulfillment/` | AdminShippingOptionType型の定義（id, label, code, description） |

**読解のコツ**: 配送オプションタイプは `label`（表示名）、`code`（識別子）、`description`（説明）の3つの主要フィールドを持つ。

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

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | shipping-option-type-list.tsx | `packages/admin/dashboard/src/routes/shipping-option-types/shipping-option-type-list/shipping-option-type-list.tsx` | ルートコンポーネント、SingleColumnPageレイアウト使用 |

**主要処理フロー**:
1. **5行目**: useExtensionでウィジェット拡張機能を取得
2. **8-16行目**: SingleColumnPageレイアウトにウィジェットとテーブルを配置

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

データテーブルの実装を読み解く。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | shipping-option-type-list-table.tsx | `packages/admin/dashboard/src/routes/shipping-option-types/shipping-option-type-list/components/shipping-option-type-list-table/shipping-option-type-list-table.tsx` | テーブル実装の中核 |

**主要処理フロー**:
- **19行目**: useTranslationで国際化対応
- **21-23行目**: useShippingOptionTypeTableQueryでクエリパラメータを管理
- **24-27行目**: useShippingOptionTypesでデータ取得
- **29行目**: useShippingOptionTypeTableFiltersでフィルタ定義
- **30行目**: useColumnsで列定義
- **32-38行目**: useDataTableでテーブル状態管理
- **57-75行目**: _DataTableコンポーネントでテーブルをレンダリング
- **82-99行目**: useColumnsで基本列にアクション列を追加

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

行のアクションメニューの実装を読み解く。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | shipping-option-type-table-row-actions.tsx | `packages/admin/dashboard/src/routes/shipping-option-types/shipping-option-type-list/components/shipping-option-type-list-table/shipping-option-type-table-row-actions.tsx` | 行アクションコンポーネント |

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

データ取得・更新のAPIフック実装を読み解く。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 5-1 | shipping-option-types.tsx | `packages/admin/dashboard/src/hooks/api/shipping-option-types.tsx` | APIフック全体 |

**主要処理フロー**:
- **41-60行目**: useShippingOptionTypesでの一覧取得
- **106-128行目**: useDeleteShippingOptionTypeでの削除処理

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

```
ShippingOptionTypeList
    │
    └─ ShippingOptionTypeListTable
           │
           ├─ useShippingOptionTypeTableQuery (クエリパラメータ管理)
           │
           ├─ useShippingOptionTypes (配送オプションタイプ一覧取得)
           │      └─ sdk.admin.shippingOptionType.list
           │
           ├─ useColumns (列定義)
           │      ├─ useShippingOptionTypeTableColumns (共通列)
           │      └─ ShippingOptionTypeRowActions (行アクション)
           │             └─ useDeleteShippingOptionTypeAction (削除処理)
           │
           ├─ useShippingOptionTypeTableFilters (フィルタ定義)
           │
           ├─ useDataTable (テーブル状態管理)
           │
           └─ _DataTable (テーブルレンダリング)
```

### データフロー図

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

URLクエリパラメータ        ───▶ useShippingOptionTypeTableQuery ───▶ searchParams
(q, limit, offset, order)

searchParams               ───▶ useShippingOptionTypes          ───▶ shipping_option_types, count
                                (APIコール)

shipping_option_types      ───▶ useDataTable                    ───▶ table (状態)

table, columns, filters    ───▶ _DataTable                      ───▶ テーブルUI
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| shipping-option-type-list.tsx | `packages/admin/dashboard/src/routes/shipping-option-types/shipping-option-type-list/` | ソース | ルートコンポーネント |
| shipping-option-type-list-table.tsx | `packages/admin/dashboard/src/routes/shipping-option-types/shipping-option-type-list/components/shipping-option-type-list-table/` | ソース | テーブルコンポーネント |
| shipping-option-type-table-row-actions.tsx | `packages/admin/dashboard/src/routes/shipping-option-types/shipping-option-type-list/components/shipping-option-type-list-table/` | ソース | 行アクションコンポーネント |
| use-shipping-option-type-table-columns.tsx | `packages/admin/dashboard/src/hooks/table/columns/` | ソース | 共通列定義フック |
| use-shipping-option-type-table-filters.tsx | `packages/admin/dashboard/src/hooks/table/filters/` | ソース | フィルタ定義フック |
| use-shipping-option-type-table-query.tsx | `packages/admin/dashboard/src/hooks/table/query/` | ソース | クエリ管理フック |
| shipping-option-types.tsx | `packages/admin/dashboard/src/hooks/api/` | ソース | APIフック |
| index.ts | `packages/admin/dashboard/src/routes/shipping-option-types/shipping-option-type-list/` | ソース | エクスポート定義 |
