# 画面設計書 79-顧客作成画面

## 概要

本ドキュメントは、Medusa Admin Dashboardにおける「顧客作成画面」の画面設計書です。新規顧客を登録するためのモーダル形式の画面について記述します。

### 本画面の処理概要

この画面では、新規顧客の基本情報を入力し、顧客レコードを作成します。メールアドレスは必須で、名前・会社名・電話番号はオプションです。

**業務上の目的・背景**：管理者が手動で顧客を登録する必要がある場合に使用します。例えば、電話や店頭での注文を受けた際に、まだシステムに登録されていない顧客を登録する場合や、B2B取引での法人顧客を事前登録する場合などに使用されます。

**画面へのアクセス方法**：顧客一覧画面（/customers）の「Create」ボタンをクリック、またはURL `/customers/create` に直接アクセスすることで表示されます。

**主要な操作・処理内容**：
1. 顧客の基本情報（名・姓・メールアドレス・会社名・電話番号）の入力
2. 入力内容のバリデーション
3. 顧客レコードの作成

**画面遷移**：
- 遷移元：顧客一覧画面
- 遷移先：作成成功時に顧客詳細画面（/customers/{id}）、キャンセル時に顧客一覧画面

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

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 49 | 顧客管理 | 主機能 | 新規顧客の作成 |

## 画面種別

モーダル形式（RouteFocusModal）

## URL/ルーティング

`/customers/create`

## 入出力項目

### フォーム項目

| 項目名 | フィールド名 | 型 | 必須 | バリデーション | 説明 |
|--------|-------------|-----|------|---------------|------|
| 名 | first_name | string | No | - | 顧客の名 |
| 姓 | last_name | string | No | - | 顧客の姓 |
| メールアドレス | email | string | Yes | 有効なメールアドレス形式 | 顧客のメールアドレス |
| 会社名 | company_name | string | No | - | 会社・組織名 |
| 電話番号 | phone | string | No | - | 電話番号 |

## 表示項目

### ヘッダー部

| 項目名 | コンポーネント | 説明 |
|--------|--------------|------|
| タイトル | Heading | "Create Customer" |
| サブタイトル | Text | 説明テキスト |

### フォーム部

| 項目名 | コンポーネント | 説明 |
|--------|--------------|------|
| 名入力 | Input | テキスト入力（optional） |
| 姓入力 | Input | テキスト入力（optional） |
| メールアドレス入力 | Input | テキスト入力（required） |
| 会社名入力 | Input | テキスト入力（optional） |
| 電話番号入力 | Input | テキスト入力（optional） |

### フッター部

| 項目名 | コンポーネント | 説明 |
|--------|--------------|------|
| キャンセルボタン | Button (secondary) | モーダルを閉じる |
| 作成ボタン | Button (primary) | 顧客を作成 |

## イベント仕様

### 1-各フィールド入力

各Inputフィールドに値を入力します。autoComplete="off"で自動補完を無効化しています。

### 2-Createボタン押下

フォームをバリデーションし、成功すれば`useCreateCustomer`フックを使用してAPIを呼び出します。

### 3-Cancelボタン押下

モーダルを閉じ、顧客一覧画面に戻ります。

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| Create押下 | customer | INSERT | 顧客レコードの作成 |

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

#### customer

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| INSERT | email | フォーム入力値 | 必須 |
| INSERT | first_name | フォーム入力値 | 空文字の場合はundefined |
| INSERT | last_name | フォーム入力値 | 空文字の場合はundefined |
| INSERT | company_name | フォーム入力値 | 空文字の場合はundefined |
| INSERT | phone | フォーム入力値 | 空文字の場合はundefined |

## メッセージ仕様

| 種別 | 条件 | メッセージ |
|------|------|-----------|
| 成功 | 顧客作成成功時 | Customer {email} was successfully created. |
| エラー | メールアドレス形式不正 | フィールドにエラーメッセージ表示 |
| エラー | API呼び出し失敗時 | エラーメッセージをトースト表示 |

## 例外処理

| 状態 | 処理 |
|------|------|
| バリデーションエラー | フォームフィールドにエラー表示 |
| API エラー発生時 | エラーメッセージをトースト表示 |

## 備考

- RouteFocusModalを使用したフルスクリーンモーダル
- フォームはreact-hook-formとzodを使用したバリデーションを実装
- 空文字の入力はundefinedに変換してAPI送信
- KeyboundFormでキーボードショートカット対応

---

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

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

### 推奨読解順序

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

ページコンポーネントの構成を確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | customer-create.tsx | `packages/admin/dashboard/src/routes/customers/customer-create/customer-create.tsx` | RouteFocusModal構成 |

**主要処理フロー**:
1. **6-9行目**: RouteFocusModalでCreateCustomerFormをラップ

#### Step 2: フォームコンポーネントを理解する

作成フォームの実装を確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | create-customer-form.tsx | `packages/admin/dashboard/src/routes/customers/customer-create/components/create-customer-form/create-customer-form.tsx` | フォーム構成、バリデーション |

**主要処理フロー**:
- **15-21行目**: CreateCustomerSchema - zodスキーマ定義
- **27行目**: useCreateCustomerでミューテーション
- **29-38行目**: useFormでフォーム初期化
- **40-63行目**: handleSubmit - バリデーションとAPI呼び出し
- **44-48行目**: 空文字をundefinedに変換

#### Step 3: API呼び出しを理解する

作成APIフックの実装を確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | customers.tsx | `packages/admin/dashboard/src/hooks/api/customers.tsx` | useCreateCustomerフック |

**主要処理フロー**:
- **64-79行目**: useCreateCustomer - ミューテーション定義、キャッシュ無効化

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

```
CustomerCreate (customer-create.tsx)
    │
    └─ RouteFocusModal
           │
           └─ CreateCustomerForm (create-customer-form.tsx)
                  │
                  ├─ useCreateCustomer()
                  │
                  ├─ useForm()
                  │      └─ zodResolver(CreateCustomerSchema)
                  │
                  ├─ KeyboundForm
                  │      │
                  │      ├─ Heading ("Create Customer")
                  │      │
                  │      ├─ Input (first_name) - optional
                  │      │
                  │      ├─ Input (last_name) - optional
                  │      │
                  │      ├─ Input (email) - required
                  │      │
                  │      ├─ Input (company_name) - optional
                  │      │
                  │      └─ Input (phone) - optional
                  │
                  └─ RouteFocusModal.Footer
                         ├─ Cancel Button
                         └─ Create Button
```

### データフロー図

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

フォーム入力 ──────▶ useForm() ──────▶ form state
                        │
                        └─▶ zodResolver(CreateCustomerSchema)

Create押下 ──────▶ handleSubmit()
                      │
                      ├─▶ 空文字をundefinedに変換
                      │      first_name: data.first_name || undefined
                      │
                      └─▶ useCreateCustomer()
                             │
                             └─▶ sdk.admin.customer.create()
                                    │
                                    └─▶ 成功: handleSuccess(`/customers/${customer.id}`)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| customer-create.tsx | `packages/admin/dashboard/src/routes/customers/customer-create/customer-create.tsx` | ソース | ページコンポーネント |
| create-customer-form.tsx | `packages/admin/dashboard/src/routes/customers/customer-create/components/create-customer-form/create-customer-form.tsx` | ソース | 作成フォーム |
| customers.tsx | `packages/admin/dashboard/src/hooks/api/customers.tsx` | ソース | API呼び出しフック |
