# 画面設計書 151-商品タグ作成画面

## 概要

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

### 本画面の処理概要

商品タグ作成画面は、ECサイトで商品をグループ化・分類するためのタグを新規に作成する機能を提供する画面である。

**業務上の目的・背景**：商品タグは商品の検索性向上やマーケティング施策（セール対象商品のグルーピングなど）において重要な役割を果たす。管理者はこの画面を通じて、任意のタグ名を入力し、システムに登録することで、後続の商品編集画面や商品一覧画面でのフィルタリングに活用できる。

**画面へのアクセス方法**：設定メニュー > 商品タグ > 「作成」ボタンをクリックすることで本画面にアクセスする。URLパスは `/settings/product-tags/create` となる。

**主要な操作・処理内容**：
1. タグ名（value）を入力フィールドに入力する
2. 「保存」ボタンをクリックしてタグを作成する
3. 作成成功時は自動的に作成されたタグの詳細画面に遷移する
4. 「キャンセル」ボタンで作成をキャンセルし、前の画面に戻る

**画面遷移**：
- 遷移元：商品タグ一覧画面（No.150）
- 遷移先：商品タグ詳細画面（No.152）- 作成成功時

**権限による表示制御**：認証済みの管理ユーザーのみがアクセス可能。特定のロールによる制限は現時点では実装されていない。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 6 | 商品タグ管理 | 主機能 | 新規商品タグの作成 |

## 画面種別

登録（モーダル形式）

## URL/ルーティング

- パス: `/settings/product-tags/create`
- コンポーネント: `ProductTagCreate`
- モーダルタイプ: `RouteFocusModal`

## 入出力項目

| 項目名 | 項目ID | 型 | 必須 | 最小長 | 最大長 | 備考 |
|--------|--------|-----|------|--------|--------|------|
| タグ名 | value | string | Yes | 1 | - | Zodスキーマで `z.string().min(1)` として定義 |

## 表示項目

| 項目名 | 説明 | 表示位置 |
|--------|------|----------|
| ヘッダータイトル | 「商品タグを作成」 | モーダルヘッダー |
| サブタイトル | 作成に関する説明文 | ヘッダー下 |
| タグ名ラベル | 「値」 | 入力フィールド上 |
| キャンセルボタン | 「キャンセル」 | フッター左 |
| 保存ボタン | 「保存」 | フッター右 |

## イベント仕様

### 1-フォーム送信（保存ボタン押下）

1. フォームバリデーションを実行（Zodスキーマによる検証）
2. バリデーション成功時、`useCreateProductTag` フックを通じて API 呼び出し
3. API呼び出し: `sdk.admin.productTag.create(data)`
4. 成功時:
   - トースト通知「タグ "{value}" が作成されました」を表示
   - 作成されたタグの詳細画面（`../{product_tag.id}`）に遷移
5. 失敗時:
   - エラーメッセージをトースト通知で表示

### 2-キャンセルボタン押下

1. モーダルを閉じる
2. 前の画面（商品タグ一覧画面）に戻る

### 3-キーボードショートカット

- `KeyboundForm` コンポーネントにより、Enter キーでフォーム送信が可能

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| 保存ボタン押下 | product_tag | INSERT | 新規商品タグレコードの作成 |

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

#### product_tag

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| INSERT | id | システム自動生成（UUID） | 主キー |
| INSERT | value | 入力された値 | タグ名 |
| INSERT | created_at | システム日時 | 作成日時 |
| INSERT | updated_at | システム日時 | 更新日時 |

## メッセージ仕様

| 種別 | メッセージキー | メッセージ内容 | 表示条件 |
|------|---------------|---------------|----------|
| 成功 | productTags.create.successToast | タグ "{value}" が作成されました | 作成成功時 |
| エラー | （APIエラーメッセージ） | APIからのエラーメッセージを表示 | 作成失敗時 |
| バリデーション | （Zodエラー） | 必須項目エラー | value が空の場合 |

## 例外処理

| 例外ケース | 処理内容 |
|-----------|---------|
| ネットワークエラー | エラーメッセージをトースト通知で表示、フォームは保持 |
| サーバーエラー | APIからのエラーメッセージをトースト通知で表示 |
| 重複エラー | APIからのエラーメッセージをトースト通知で表示 |

## 備考

- モーダルは `RouteFocusModal` コンポーネントを使用しており、フルスクリーンのオーバーレイとして表示される
- フォーム状態管理には react-hook-form を使用
- バリデーションには Zod スキーマを使用
- キャッシュ無効化: 作成成功時に `productTagsQueryKeys.lists()` のキャッシュを無効化

---

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

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

### 推奨読解順序

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

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | HttpTypes | `@medusajs/types` | `AdminCreateProductTag`, `AdminProductTagResponse` の型定義を確認 |
| 1-2 | ProductTagCreateSchema | `product-tag-create-form.tsx:14-16` | Zodによるバリデーションスキーマの定義 |

**読解のコツ**: Zodスキーマは `z.object({ value: z.string().min(1) })` と定義されており、value フィールドが最小1文字以上の文字列であることが必須条件。

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

処理の起点となるコンポーネントを特定する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | ProductTagCreate | `packages/admin/dashboard/src/routes/product-tags/product-tag-create/product-tag-create.tsx` | RouteFocusModal でラップされたエントリーポイント |
| 2-2 | ProductTagCreateForm | `packages/admin/dashboard/src/routes/product-tags/product-tag-create/components/product-tag-create-form/product-tag-create-form.tsx` | 実際のフォームロジック |

**主要処理フロー**:
1. **行18-27**: useForm による初期化、defaultValues と resolver の設定
2. **行29**: useCreateProductTag フックの呼び出し
3. **行31-45**: handleSubmit 関数でフォーム送信処理、成功/失敗時のコールバック定義
4. **行47-99**: JSX レンダリング（フォーム要素、入力フィールド、ボタン）

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

バックエンドとの通信を担うフックの実装を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | useCreateProductTag | `packages/admin/dashboard/src/hooks/api/tags.tsx:92-110` | useMutation によるAPI呼び出しとキャッシュ無効化 |

**主要処理フロー**:
- **行100-101**: `sdk.admin.productTag.create(data, query)` によるAPI呼び出し
- **行102-105**: 成功時に `productTagsQueryKeys.lists()` のキャッシュを無効化

#### Step 4: モーダルコンポーネントを理解する

UIコンポーネントの構造を把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | RouteFocusModal | `packages/admin/dashboard/src/components/modals` | モーダルの基本構造（Header, Body, Footer） |
| 4-2 | KeyboundForm | `packages/admin/dashboard/src/components/utilities/keybound-form` | キーボードショートカット対応フォーム |

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

```
ProductTagCreate（エントリーポイント）
    │
    └─ RouteFocusModal
           │
           └─ ProductTagCreateForm
                  │
                  ├─ useForm (react-hook-form)
                  │      └─ zodResolver (Zod バリデーション)
                  │
                  ├─ useCreateProductTag (API呼び出し)
                  │      └─ useMutation (TanStack Query)
                  │             └─ sdk.admin.productTag.create()
                  │
                  └─ handleSubmit
                         ├─ onSuccess → toast.success() + handleSuccess()
                         └─ onError → toast.error()
```

### データフロー図

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

value (string) ───▶ ProductTagCreateForm ───▶ 商品タグ詳細画面
                          │
                          ├─ Zod バリデーション
                          │
                          ├─ useCreateProductTag
                          │      │
                          │      └─ POST /admin/product-tags
                          │              │
                          │              └─ product_tag データ
                          │
                          └─ handleSuccess("../{id}")
                                 │
                                 └─ 画面遷移
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| product-tag-create.tsx | `packages/admin/dashboard/src/routes/product-tags/product-tag-create/product-tag-create.tsx` | ソース | エントリーポイントコンポーネント |
| product-tag-create-form.tsx | `packages/admin/dashboard/src/routes/product-tags/product-tag-create/components/product-tag-create-form/product-tag-create-form.tsx` | ソース | フォームロジックとUI |
| tags.tsx | `packages/admin/dashboard/src/hooks/api/tags.tsx` | ソース | 商品タグ関連APIフック |
| index.ts | `packages/admin/dashboard/src/routes/product-tags/product-tag-create/index.ts` | ソース | モジュールエクスポート |
