# 画面設計書 156-商品タイプ作成画面

## 概要

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

### 本画面の処理概要

商品タイプ作成画面は、ECサイトで商品を分類するためのタイプを新規に作成する機能を提供する画面である。商品タイプは商品の種類を定義するために使用される。

**業務上の目的・背景**：商品タイプは商品の大分類として機能し、「衣類」「電子機器」「食品」など、商品の基本的なカテゴリを定義する。これにより、商品の管理・検索・分析が効率化され、顧客への商品提案の精度も向上する。

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

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

**画面遷移**：
- 遷移元：商品タイプ一覧画面（No.155）
- 遷移先：商品タイプ詳細画面（No.157）- 作成成功時

**権限による表示制御**：認証済みの管理ユーザーのみがアクセス可能。

## 関連機能

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

## 画面種別

登録（モーダル形式）

## URL/ルーティング

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

## 入出力項目

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

## 表示項目

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

## イベント仕様

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

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

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

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

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

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

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

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

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

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

#### product_type

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

## メッセージ仕様

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

## 例外処理

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

## 備考

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

---

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

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

### 推奨読解順序

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

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

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

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

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

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

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

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

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

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

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

**主要処理フロー**:
- **行100**: `sdk.admin.productType.create(payload)` によるAPI呼び出し
- **行101-104**: 成功時に `productTypesQueryKeys.lists()` のキャッシュを無効化

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

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

### データフロー図

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

value (string) ───▶ CreateProductTypeForm ───▶ 商品タイプ詳細画面
                          │
                          ├─ Zod バリデーション
                          │
                          ├─ useCreateProductType
                          │      │
                          │      └─ POST /admin/product-types
                          │              │
                          │              └─ product_type データ
                          │
                          └─ handleSuccess("/settings/product-types/{id}")
                                 │
                                 └─ 画面遷移
```

### 関連ファイル一覧

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