# 画面設計書 152-商品タグ詳細画面

## 概要

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

### 本画面の処理概要

商品タグ詳細画面は、特定の商品タグの詳細情報を表示し、そのタグに紐付けられた商品の一覧を確認できる画面である。管理者はこの画面から、タグの編集、削除、メタデータ管理、および翻訳管理（機能が有効な場合）を行うことができる。

**業務上の目的・背景**：商品タグは商品の分類やマーケティング施策において重要な役割を果たす。この画面では、タグの詳細情報と、そのタグが付与されている商品の一覧を一目で確認できるため、タグの使用状況を把握し、適切な管理を行うことが可能となる。

**画面へのアクセス方法**：
1. 設定メニュー > 商品タグ > タグ一覧から任意のタグをクリック
2. 商品タグ作成画面から作成完了後に自動遷移
3. 直接URL `/settings/product-tags/{id}` にアクセス

**主要な操作・処理内容**：
1. タグの基本情報（タグ名）を表示する
2. タグに紐付いた商品一覧を表示・検索・フィルタリングする
3. 「編集」アクションからタグ名を編集する
4. 「削除」アクションからタグを削除する
5. 翻訳管理画面への遷移（翻訳機能が有効な場合）
6. メタデータ・JSON表示の確認

**画面遷移**：
- 遷移元：商品タグ一覧画面（No.150）、商品タグ作成画面（No.151）
- 遷移先：商品タグ編集画面（No.153）、タグメタデータ編集画面（No.154）、商品詳細画面（No.7）、翻訳管理画面

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

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 6 | 商品タグ管理 | 主機能 | 商品タグ詳細の表示 |
| 1 | 商品CRUD | 補助機能 | タグ付き商品の表示 |

## 画面種別

詳細

## URL/ルーティング

- パス: `/settings/product-tags/:id`
- コンポーネント: `ProductTagDetail`
- ローダー: `productTagLoader`

## 入出力項目

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

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|-----|------|------|
| id | string | Yes | 商品タグのID |

## 表示項目

### 一般情報セクション

| 項目名 | 説明 | 備考 |
|--------|------|------|
| タグ名 | タグの値（value） | # プレフィックス付きで表示 |
| アクションメニュー | 編集・削除・翻訳管理 | ドロップダウンメニュー |

### 商品一覧セクション

| 項目名 | 説明 | 備考 |
|--------|------|------|
| セクションタイトル | 「商品」 | - |
| 商品タイトル | 商品名 | - |
| 商品ステータス | 公開/下書きなど | - |
| 作成日時 | 商品作成日 | - |
| 更新日時 | 商品更新日 | - |

### ページ共通

| 項目名 | 説明 | 備考 |
|--------|------|------|
| JSON表示 | 商品タグの生データ | showJSON=true |
| メタデータ表示 | メタデータ情報 | showMetadata=true |

## イベント仕様

### 1-編集ボタン押下

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

### 2-削除ボタン押下

1. アクションメニューから「削除」を選択
2. 確認ダイアログを表示
   - タイトル: 「本当に削除しますか?」
   - 説明: タグ名を含む確認メッセージ
3. 「削除」確認時:
   - `useDeleteProductTag` フックで API 呼び出し
   - 成功時: トースト通知「タグ "{value}" が削除されました」を表示
   - 商品タグ一覧画面（`/settings/product-tags`）に遷移
4. 「キャンセル」時: ダイアログを閉じる

### 3-翻訳管理ボタン押下

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

### 4-商品行クリック

1. 商品一覧から任意の商品行をクリック
2. 商品詳細画面（`/products/{product_id}`）に遷移

### 5-商品一覧の検索・ソート

1. 検索バーで商品タイトルをキーワード検索
2. ソートオプション: タイトル、ステータス、作成日、更新日
3. フィルタリング: 商品タグ以外のフィルタ条件を適用可能

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

1. 商品一覧は10件/ページで表示
2. ページ切り替えで次/前のページを表示

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| 画面表示 | product_tag | SELECT | タグ詳細情報の取得 |
| 画面表示 | product | SELECT | タグに紐付く商品一覧の取得 |
| 削除ボタン押下 | product_tag | DELETE | タグの削除 |

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

#### product_tag（参照）

| 操作 | 項目（カラム名） | 取得条件 | 備考 |
|-----|-----------------|---------|------|
| SELECT | id, value, metadata, created_at, updated_at | WHERE id = :id | タグ詳細情報 |

#### product（参照）

| 操作 | 項目（カラム名） | 取得条件 | 備考 |
|-----|-----------------|---------|------|
| SELECT | id, title, status, created_at, updated_at | WHERE tag_id = :tag_id | タグ付き商品一覧 |

## メッセージ仕様

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

## 例外処理

| 例外ケース | 処理内容 |
|-----------|---------|
| タグが存在しない | エラーをスロー（エラー境界でキャッチ） |
| ネットワークエラー | エラーメッセージをトースト通知で表示 |
| データ読み込み中 | スケルトンローダーを表示 |

## 備考

- `SingleColumnPage` レイアウトを使用
- 拡張ウィジェット対応: `product_tag.details.before`, `product_tag.details.after`
- 商品一覧はプレフィックス `pt` を使用してURLパラメータを管理
- 商品テーブルでは商品タグフィルタを除外（自身のタグでフィルタ済みのため）

---

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

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

### 推奨読解順序

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

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | HttpTypes | `@medusajs/types` | `AdminProductTag`, `AdminProduct` の型定義 |
| 1-2 | loader.ts | `packages/admin/dashboard/src/routes/product-tags/product-tag-detail/loader.ts` | ローダーによるデータプリフェッチ |

**読解のコツ**: ローダーは `queryClient.ensureQueryData()` を使用してデータをプリフェッチし、コンポーネントでの初期表示を高速化している。

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

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

**主要処理フロー**:
1. **行12-13**: useParams と useLoaderData でIDとプリフェッチデータを取得
2. **行20-26**: useProductTag フックでタグデータを取得（初期データ付き）
3. **行28-34**: ローディング・エラー状態の処理
4. **行36-48**: SingleColumnPage 内に各セクションをレンダリング

#### Step 3: 各セクションコンポーネントを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | ProductTagGeneralSection | `packages/admin/dashboard/src/routes/product-tags/product-tag-detail/components/product-tag-general-section/product-tag-general-section.tsx` | 基本情報とアクションメニュー |
| 3-2 | ProductTagProductSection | `packages/admin/dashboard/src/routes/product-tags/product-tag-detail/components/product-tag-product-section/product-tag-product-section.tsx` | 商品一覧テーブル |

**ProductTagGeneralSection の主要処理**:
- **行17**: useDeleteProductTagAction フックで削除処理を取得
- **行18**: useFeatureFlag で翻訳機能の有効状態を確認
- **行26-58**: ActionMenu でアクショングループを構成

**ProductTagProductSection の主要処理**:
- **行23-26**: useProductTableQuery でテーブルクエリパラメータを管理
- **行28-31**: useProducts で商品一覧を取得（tag_id でフィルタ）
- **行33-34**: テーブルフィルタとカラムを設定
- **行54-71**: _DataTable でテーブルをレンダリング

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

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

**主要処理フロー**:
- **行18**: useDeleteProductTag でミューテーションフックを取得
- **行20-28**: prompt で確認ダイアログを表示
- **行34-48**: 削除実行と結果ハンドリング

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

```
ProductTagDetail（エントリーポイント）
    │
    ├─ productTagLoader（ルートローダー）
    │      └─ queryClient.ensureQueryData()
    │
    ├─ useProductTag（タグデータ取得）
    │      └─ sdk.admin.productTag.retrieve()
    │
    ├─ SingleColumnPage（レイアウト）
    │      │
    │      ├─ ProductTagGeneralSection
    │      │      ├─ useDeleteProductTagAction
    │      │      │      └─ useDeleteProductTag
    │      │      │             └─ sdk.admin.productTag.delete()
    │      │      └─ ActionMenu
    │      │
    │      └─ ProductTagProductSection
    │             ├─ useProducts
    │             │      └─ sdk.admin.product.list({ tag_id })
    │             └─ _DataTable
```

### データフロー図

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

URL params (id) ───▶ ProductTagDetail ───▶ タグ詳細表示
                          │
                          ├─ useProductTag
                          │      │
                          │      └─ GET /admin/product-tags/{id}
                          │              │
                          │              └─ product_tag データ
                          │
                          ├─ ProductTagGeneralSection
                          │      │
                          │      └─ ActionMenu（編集/削除/翻訳）
                          │
                          └─ ProductTagProductSection
                                 │
                                 └─ GET /admin/products?tag_id={id}
                                        │
                                        └─ 商品一覧データ
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| product-tag-detail.tsx | `packages/admin/dashboard/src/routes/product-tags/product-tag-detail/product-tag-detail.tsx` | ソース | メインコンポーネント |
| loader.ts | `packages/admin/dashboard/src/routes/product-tags/product-tag-detail/loader.ts` | ソース | データローダー |
| product-tag-general-section.tsx | `packages/admin/dashboard/src/routes/product-tags/product-tag-detail/components/product-tag-general-section/product-tag-general-section.tsx` | ソース | 基本情報セクション |
| product-tag-product-section.tsx | `packages/admin/dashboard/src/routes/product-tags/product-tag-detail/components/product-tag-product-section/product-tag-product-section.tsx` | ソース | 商品一覧セクション |
| use-delete-product-tag-action.tsx | `packages/admin/dashboard/src/routes/product-tags/common/hooks/use-delete-product-tag-action.tsx` | ソース | 削除処理フック |
| tags.tsx | `packages/admin/dashboard/src/hooks/api/tags.tsx` | ソース | 商品タグAPIフック |
| breadcrumb.tsx | `packages/admin/dashboard/src/routes/product-tags/product-tag-detail/breadcrumb.tsx` | ソース | パンくずナビゲーション |
