# 画面設計書 150-商品タグ一覧画面

## 概要

本ドキュメントは、Medusa Admin Dashboard における商品タグ一覧画面の設計仕様を記述したものである。

### 本画面の処理概要

**業務上の目的・背景**：商品タグは、商品を分類・整理するためのラベルであり、商品検索や商品グルーピングに使用される。本画面では、システムに登録されている全ての商品タグを一覧で確認し、新規作成、編集、削除などの管理操作を行うことができる。

**画面へのアクセス方法**：サイドバーの「設定」>「商品タグ」からアクセスする。URLパスは `/settings/product-tags` である。

**主要な操作・処理内容**：
1. 商品タグの一覧を表示する
2. 商品タグを検索する
3. 日付フィルターでタグを絞り込む
4. 並び替え（値、作成日時、更新日時）を行う
5. 新しい商品タグを作成する
6. 商品タグを編集する
7. 商品タグを削除する
8. 翻訳を管理する（翻訳機能が有効な場合）

**画面遷移**：
- 遷移元: サイドバーの設定メニュー
- 遷移先: 商品タグ作成画面、商品タグ詳細画面、商品タグ編集画面、翻訳編集画面

**権限による表示制御**：管理者権限を持つユーザーのみアクセス可能。商品タグ管理権限がない場合は表示されない。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 2 | 商品管理 | 主機能 | 商品タグの一覧表示・管理 |

## 画面種別

一覧

## URL/ルーティング

```
/settings/product-tags
```

## 入出力項目

### クエリパラメータ

| 項目名 | 項目ID | データ型 | 必須 | 説明 |
|--------|--------|----------|------|------|
| 検索クエリ | q | string | - | 値での検索キーワード |
| 作成日フィルター | created_at | object | - | 作成日時の範囲フィルター |
| 更新日フィルター | updated_at | object | - | 更新日時の範囲フィルター |
| 並び替え | order | string | - | ソート対象フィールド |
| オフセット | offset | number | - | ページネーションのオフセット |
| 件数 | limit | number | - | 1ページあたりの表示件数（デフォルト: 20） |

## 表示項目

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

| 項目名 | 説明 |
|--------|------|
| タイトル | 「商品タグ」（productTags.domain） |
| 作成ボタン | 新規作成画面へのリンク |

### テーブルカラム

| 項目名 | 項目ID | データソース | 説明 |
|--------|--------|-------------|------|
| 値 | value | product_tag.value | 商品タグの値（表示名） |
| 作成日時 | created_at | product_tag.created_at | タグの作成日時 |
| 更新日時 | updated_at | product_tag.updated_at | タグの更新日時 |
| アクション | actions | - | 行アクションメニュー |

### フィルター

| フィルター名 | フィルターキー | 種別 | 説明 |
|------------|--------------|------|------|
| 作成日時 | created_at | date | 作成日時の範囲フィルター |
| 更新日時 | updated_at | date | 更新日時の範囲フィルター |

### 並び替えオプション

| 項目名 | フィールド | 説明 |
|--------|----------|------|
| 値 | value | 値の昇順/降順 |
| 作成日時 | created_at | 作成日時の昇順/降順 |
| 更新日時 | updated_at | 更新日時の昇順/降順 |

## イベント仕様

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

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

**処理フロー**：
1. `/settings/product-tags/create` へ遷移
2. 商品タグ作成画面（モーダル）を表示

### 2-行クリック

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

**処理フロー**：
1. クリックした行のproduct_tag.idを取得
2. `/settings/product-tags/:id` へ遷移
3. 商品タグ詳細画面を表示

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

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

**処理フロー**：
1. `/settings/product-tags/:id/edit` へ遷移
2. 商品タグ編集画面（モーダル）を表示

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

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

**処理フロー**：
1. 確認プロンプトを表示（「削除してもよろしいですか？」）
2. ユーザーが確認した場合、`useDeleteProductTag` フックを使用してAPIを呼び出し
3. 成功時: 成功トーストを表示し、一覧画面へ遷移
4. 失敗時: エラートーストを表示

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

**トリガー**：行のアクションメニューから「翻訳を管理」を選択（翻訳機能が有効な場合のみ）

**処理フロー**：
1. `/settings/translations/edit?reference=product_tag&reference_id=:id` へ遷移
2. 翻訳編集画面を表示

### 6-検索実行

**トリガー**：検索フィールドに入力

**処理フロー**：
1. クエリパラメータqを更新
2. APIを再呼び出しして結果を表示

### 7-フィルター変更

**トリガー**：フィルター（作成日時・更新日時）を変更

**処理フロー**：
1. 対応するクエリパラメータを更新
2. APIを再呼び出しして結果を表示

### 8-並び替え変更

**トリガー**：並び替えオプションを変更

**処理フロー**：
1. orderクエリパラメータを更新
2. APIを再呼び出しして結果を表示

### 9-ページネーション

**トリガー**：ページを変更

**処理フロー**：
1. offsetクエリパラメータを更新
2. APIを再呼び出しして結果を表示

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| 削除アクション | product_tag | DELETE | 商品タグを削除 |

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

#### product_tag

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| DELETE | id | 対象の商品タグID | 削除対象の特定 |

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 | 表示条件 |
|-------------|------|---------------|----------|
| general.areYouSure | 確認 | 本当によろしいですか？ | 削除アクション選択時 |
| productTags.delete.confirmation | 確認 | {value}を削除します | 削除アクション選択時 |
| productTags.delete.successToast | 成功 | {value}を削除しました | 削除成功時 |
| - | エラー | {APIエラーメッセージ} | API呼び出し失敗時 |

## 例外処理

| 例外条件 | 処理内容 |
|---------|---------|
| 商品タグ一覧取得失敗 | エラーをthrowし、エラーページを表示 |
| 削除処理失敗 | エラートーストを表示 |
| ネットワークエラー | エラートーストを表示 |

## 備考

- SingleColumnPageレイアウトを使用
- showMetadata と showJSON オプションは無効
- hasOutlet が有効（子ルートのアウトレットあり）
- 拡張ウィジェット（before/after）をサポート
- useLoaderDataでサーバーサイドレンダリング用の初期データを取得
- keepPreviousDataでページ遷移時のちらつきを防止
- 翻訳機能は機能フラグ「translation」で制御

---

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

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

### 推奨読解順序

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

商品タグのデータ構造を把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | HttpTypes | `packages/core/types/src/http/product/` | AdminProductTag型の定義（id, value, created_at, updated_at, metadata） |

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

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

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | product-tag-list.tsx | `packages/admin/dashboard/src/routes/product-tags/product-tag-list/product-tag-list.tsx` | ルートコンポーネント |

**主要処理フロー**:
1. **6行目**: useExtensionでウィジェット拡張機能を取得
2. **9-19行目**: SingleColumnPageレイアウトでProductTagListTableをラップ
3. **13-16行目**: 拡張ウィジェット（before/after）を設定

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

一覧テーブルの実装を読み解く。

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

**主要処理フロー**:
- **21行目**: PAGE_SIZE = 20でページサイズ定義
- **24行目**: useTranslationで国際化対応
- **25-27行目**: useProductTagTableQueryでクエリパラメータを構築
- **29-31行目**: useLoaderDataで初期データを取得
- **33-39行目**: useProductTagsでデータ取得
- **41行目**: useColumnsでカラム定義を取得
- **42行目**: useProductTagTableFiltersでフィルター定義を取得
- **44-50行目**: useDataTableでテーブル状態を管理
- **52-54行目**: エラー時はerrorをthrow
- **56-82行目**: _DataTableでテーブルをレンダリング

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

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | product-tag-list-table.tsx | `packages/admin/dashboard/src/routes/product-tags/product-tag-list/components/product-tag-list-table/product-tag-list-table.tsx` | ProductTagRowActionsコンポーネント（85-131行目） |

**主要処理フロー**:
- **91行目**: useDeleteProductTagActionで削除処理を取得
- **92行目**: useFeatureFlagで翻訳機能の有効状態を確認
- **96-128行目**: ActionMenuで編集・翻訳・削除アクションを提供

#### Step 5: 削除アクションフックを理解する

削除処理の共通フック実装を読み解く。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 5-1 | use-delete-product-tag-action.tsx | `packages/admin/dashboard/src/routes/product-tags/common/hooks/use-delete-product-tag-action.tsx` | 削除アクションフック |

**主要処理フロー**:
- **15行目**: usePromptで確認ダイアログ
- **18行目**: useDeleteProductTagで削除ミューテーション
- **20-48行目**: handleDeleteで確認後に削除を実行
- **36-40行目**: 成功時のコールバック（トースト表示、一覧画面へ遷移）
- **45-46行目**: エラー時のコールバック

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

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 6-1 | tags.tsx | `packages/admin/dashboard/src/hooks/api/tags.tsx` | useProductTags, useDeleteProductTag |

**主要処理フロー**:
- **42-61行目**: useProductTagsでの一覧取得
- **138-160行目**: useDeleteProductTagでの削除処理

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

```
ProductTagList
    |
    +- useExtension (ウィジェット拡張)
    |
    +- SingleColumnPage
           |
           +- ProductTagListTable
                  |
                  +- useTranslation (国際化)
                  |
                  +- useProductTagTableQuery (クエリパラメータ)
                  |
                  +- useLoaderData (初期データ)
                  |
                  +- useProductTags (データ取得)
                  |      +- sdk.admin.productTag.list
                  |
                  +- useColumns
                  |      +- useProductTagTableColumns
                  |             +- columnHelper (value, created_at, updated_at)
                  |
                  +- useProductTagTableFilters
                  |      +- useDateTableFilters (created_at, updated_at)
                  |
                  +- useDataTable (テーブル状態管理)
                  |
                  +- _DataTable (テーブルUI)
                         |
                         +- ProductTagRowActions
                                |
                                +- useDeleteProductTagAction
                                |      +- useDeleteProductTag
                                |      +- usePrompt
                                |
                                +- useFeatureFlag("translation")
                                |
                                +- ActionMenu (編集/翻訳/削除)
```

### データフロー図

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

クエリパラメータ            ---> useProductTagTableQuery        ---> searchParams
(q, created_at, updated_at,      (クエリ構築)
 order, offset)

searchParams                ---> useProductTags                 ---> product_tags, count
                                 (APIコール)

product_tags               ---> useDataTable                    ---> table
                                (テーブル状態管理)

table                      ---> _DataTable                      ---> テーブルUI
                                (レンダリング)

削除アクション             ---> useDeleteProductTagAction      ---> 削除結果
                                (削除処理)
                                |
                           ---> navigate                        ---> 一覧画面へ遷移
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| product-tag-list.tsx | `packages/admin/dashboard/src/routes/product-tags/product-tag-list/` | ソース | ルートコンポーネント |
| product-tag-list-table.tsx | `packages/admin/dashboard/src/routes/product-tags/product-tag-list/components/product-tag-list-table/` | ソース | 一覧テーブル |
| use-delete-product-tag-action.tsx | `packages/admin/dashboard/src/routes/product-tags/common/hooks/` | ソース | 削除アクションフック |
| use-product-tag-table-columns.tsx | `packages/admin/dashboard/src/hooks/table/columns/` | ソース | カラム定義 |
| use-product-tag-table-filters.tsx | `packages/admin/dashboard/src/hooks/table/filters/` | ソース | フィルター定義 |
| loader.ts | `packages/admin/dashboard/src/routes/product-tags/product-tag-list/` | ソース | データローダー |
| tags.tsx | `packages/admin/dashboard/src/hooks/api/` | ソース | APIフック |
| index.ts | `packages/admin/dashboard/src/routes/product-tags/product-tag-list/` | ソース | エクスポート定義 |
