# 画面設計書 155-商品タイプ一覧画面

## 概要

本ドキュメントは、Medusa Admin Dashboard における商品タイプ一覧画面の設計仕様を定義するものである。

### 本画面の処理概要

商品タイプ一覧画面は、システムに登録されている商品タイプの一覧を表示し、管理するための画面である。商品タイプは商品の分類に使用され、管理者はこの画面から新規タイプの作成、既存タイプの詳細確認、編集、削除を行うことができる。

**業務上の目的・背景**：商品タイプは商品を種類別に分類するための重要な属性である。例えば「衣類」「電子機器」「食品」などのタイプを設定することで、商品管理や検索の効率化、レポーティングの精度向上に貢献する。この画面では、登録されている全タイプを一覧で把握し、必要に応じて管理操作を行うことができる。

**画面へのアクセス方法**：
1. 設定メニュー > 商品タイプ をクリック
2. 直接URL `/settings/product-types` にアクセス

**主要な操作・処理内容**：
1. 商品タイプの一覧を表示する（ページネーション対応、20件/ページ）
2. 検索バーで商品タイプを検索する
3. ソートオプションで一覧を並び替える（値、作成日、更新日）
4. 「作成」ボタンから新規商品タイプを作成する
5. 行クリックで商品タイプ詳細画面に遷移する
6. 行のアクションメニューから編集・削除を実行する

**画面遷移**：
- 遷移元：設定トップ画面（No.105）
- 遷移先：商品タイプ作成画面（No.156）、商品タイプ詳細画面（No.157）、商品タイプ編集画面（No.158）、翻訳管理画面

**権限による表示制御**：認証済みの管理ユーザーのみがアクセス可能。翻訳管理メニューは翻訳機能フラグが有効な場合のみ表示される。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 7 | 商品タイプ管理 | 主機能 | 商品タイプ一覧の取得・表示 |

## 画面種別

一覧

## URL/ルーティング

- パス: `/settings/product-types`
- コンポーネント: `ProductTypeList`

## 入出力項目

本画面は一覧表示画面のため、入力項目はなし。URLクエリパラメータとして以下を受け取る。

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|-----|------|------|
| offset | number | No | ページネーションのオフセット |
| q | string | No | 検索クエリ |
| order | string | No | ソート順 |

## 表示項目

### ヘッダーセクション

| 項目名 | 説明 | 備考 |
|--------|------|------|
| タイトル | 「商品タイプ」 | - |
| サブタイトル | 説明文 | - |
| 作成ボタン | 「作成」 | 新規作成画面への遷移 |

### テーブルセクション

| 項目名 | 説明 | 備考 |
|--------|------|------|
| 値（value） | タイプ名 | - |
| 作成日 | 作成日時 | - |
| 更新日 | 更新日時 | - |
| アクション | 編集・削除メニュー | 行ごと |

### ツールバー

| 項目名 | 説明 | 備考 |
|--------|------|------|
| 検索バー | タイプ名検索 | - |
| ソートセレクト | 値、作成日、更新日 | - |
| ページネーション | ページ切り替え | 20件/ページ |

## イベント仕様

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

1. 商品タイプ作成画面（`/settings/product-types/create`）に遷移

### 2-行クリック

1. クリックされた商品タイプの詳細画面（`/settings/product-types/{id}`）に遷移

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

1. アクションメニューから「編集」を選択
2. 商品タイプ編集画面（`/settings/product-types/{id}/edit`）に遷移

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

1. アクションメニューから「削除」を選択
2. 確認ダイアログを表示
3. 「削除」確認時:
   - `useDeleteProductType` フックで API 呼び出し
   - 成功時: トースト通知「タイプ "{value}" が削除されました」を表示
   - 一覧を再取得（キャッシュ無効化）
4. 「キャンセル」時: ダイアログを閉じる

### 5-翻訳管理アクション押下

1. アクションメニューから「翻訳を管理」を選択（翻訳機能有効時のみ表示）
2. 翻訳編集画面（`/settings/translations/edit?reference=product_type&reference_id={id}`）に遷移

### 6-検索実行

1. 検索バーにキーワードを入力
2. Enter または検索アイコンクリックで検索実行
3. 一覧が検索結果でフィルタリングされる

### 7-ソート変更

1. ソートセレクトから項目を選択（値、作成日、更新日）
2. 一覧が選択した項目で並び替えられる

### 8-ページ切り替え

1. ページネーションコントロールで次/前ページを選択
2. 該当ページのデータが表示される

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| 画面表示 | product_type | SELECT | タイプ一覧の取得 |
| 削除アクション | product_type | DELETE | タイプの削除 |

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

#### product_type

| 操作 | 項目（カラム名） | 取得条件 | 備考 |
|-----|-----------------|---------|------|
| SELECT | id, value, created_at, updated_at | ページネーション、検索、ソート条件適用 | 一覧取得 |
| DELETE | - | WHERE id = :id | タイプ削除 |

## メッセージ仕様

| 種別 | メッセージキー | メッセージ内容 | 表示条件 |
|------|---------------|---------------|----------|
| 成功 | productTypes.delete.successToast | タイプ "{value}" が削除されました | 削除成功時 |
| 確認 | general.areYouSure | 本当に削除しますか? | 削除確認ダイアログ |
| 確認 | productTypes.delete.confirmation | タイプ "{value}" を削除しますか? | 削除確認ダイアログ |
| エラー | （APIエラー） | APIからのエラーメッセージ | 削除失敗時 |

## 例外処理

| 例外ケース | 処理内容 |
|-----------|---------|
| ネットワークエラー | エラーをスロー（エラー境界でキャッチ） |
| データなし | 「レコードがありません」メッセージを表示 |
| 検索結果なし | 「結果がありません」メッセージを表示 |

## 備考

- `SingleColumnPage` レイアウトを使用
- 拡張ウィジェット対応: `product_type.list.before`, `product_type.list.after`
- ページサイズは 20 件固定
- `keepPreviousData` オプションでページ切り替え時のちらつきを防止
- カラム定義は `useProductTypeTableColumns` フックで管理

---

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

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

### 推奨読解順序

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

まず、商品タイプのデータ構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | HttpTypes | `@medusajs/types` | `AdminProductType`, `AdminProductTypeListParams` の型定義 |

**読解のコツ**: 商品タイプは `id`, `value`, `created_at`, `updated_at`, `metadata` を持つシンプルな構造。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | ProductTypeList | `packages/admin/dashboard/src/routes/product-types/product-type-list/product-type-list.tsx` | SingleColumnPage でラップ |

**主要処理フロー**:
1. **行6**: getWidgets で拡張ウィジェットを取得
2. **行8-16**: SingleColumnPage 内に ProductTypeListTable を配置

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

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

**主要処理フロー**:
- **行17**: PAGE_SIZE = 20 定数定義
- **行22-24**: useProductTypeTableQuery でクエリパラメータ管理
- **行25-30**: useProductTypes で API 呼び出し
- **行32-33**: フィルタとカラムの設定
- **行35-41**: useDataTable でテーブル状態管理
- **行47-78**: JSX レンダリング（ヘッダー、テーブル）
- **行83-98**: useColumns でカラム定義（アクション列を追加）

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | ProductTypeRowActions | `packages/admin/dashboard/src/routes/product-types/product-type-list/components/product-type-list-table/product-table-row-actions.tsx` | 行ごとのアクションメニュー |

#### Step 5: 削除処理フックを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 5-1 | useDeleteProductTypeAction | `packages/admin/dashboard/src/routes/product-types/common/hooks/use-delete-product-type-action.tsx` | 削除処理のカスタムフック |

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

```
ProductTypeList（エントリーポイント）
    │
    ├─ useExtension（拡張ウィジェット）
    │
    └─ SingleColumnPage
           │
           └─ ProductTypeListTable
                  │
                  ├─ useProductTypeTableQuery（クエリ管理）
                  │
                  ├─ useProductTypes（API呼び出し）
                  │      └─ sdk.admin.productType.list()
                  │
                  ├─ useProductTypeTableFilters（フィルタ）
                  │
                  ├─ useColumns
                  │      ├─ useProductTypeTableColumns（基本カラム）
                  │      └─ ProductTypeRowActions（アクション列）
                  │             │
                  │             ├─ useDeleteProductTypeAction
                  │             │      └─ useDeleteProductType
                  │             │
                  │             └─ useFeatureFlag（翻訳機能）
                  │
                  └─ useDataTable（テーブル状態管理）
```

### データフロー図

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

URL query params ───▶ ProductTypeListTable ───▶ テーブル表示
                          │
                          ├─ useProductTypeTableQuery
                          │      │
                          │      └─ searchParams, raw
                          │
                          ├─ useProductTypes
                          │      │
                          │      └─ GET /admin/product-types
                          │              │
                          │              └─ product_types, count
                          │
                          └─ useDataTable
                                 │
                                 └─ table state
                                        │
                                        └─ _DataTable レンダリング
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| product-type-list.tsx | `packages/admin/dashboard/src/routes/product-types/product-type-list/product-type-list.tsx` | ソース | エントリーポイント |
| product-type-list-table.tsx | `packages/admin/dashboard/src/routes/product-types/product-type-list/components/product-type-list-table/product-type-list-table.tsx` | ソース | テーブルコンポーネント |
| product-table-row-actions.tsx | `packages/admin/dashboard/src/routes/product-types/product-type-list/components/product-type-list-table/product-table-row-actions.tsx` | ソース | 行アクションメニュー |
| use-delete-product-type-action.tsx | `packages/admin/dashboard/src/routes/product-types/common/hooks/use-delete-product-type-action.tsx` | ソース | 削除処理フック |
| product-types.tsx | `packages/admin/dashboard/src/hooks/api/product-types.tsx` | ソース | 商品タイプAPIフック |
