# 画面設計書 54-メールアドレス編集画面

## 概要

本ドキュメントは、Medusa Admin Dashboard における「メールアドレス編集画面」の設計仕様を定義するものである。

### 本画面の処理概要

**業務上の目的・背景**：EC運営において、顧客が注文後にメールアドレスの変更を希望する場合や、入力ミスの修正が必要な場合がある。本画面は、管理者が注文に紐づくメールアドレスを編集するためのインターフェースを提供する。これにより、注文確認メールや配送通知等の送信先を適切に管理できる。

**画面へのアクセス方法**：注文詳細画面から「メールアドレス編集」アクションを選択することでアクセスする。

**主要な操作・処理内容**：
1. 現在のメールアドレスを確認する
2. 新しいメールアドレスを入力する
3. 保存ボタンを押下してメールアドレスを更新する

**画面遷移**：
- 遷移元：注文詳細画面（`/orders/:id`）
- 遷移先：更新完了後、注文詳細画面に戻る

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

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 26 | 注文情報更新 | 主機能 | 注文メールアドレスの更新 |

## 画面種別

編集（ドロワー形式）

## URL/ルーティング

```
/orders/:id/email
```

## 入出力項目

| 項目名 | 項目ID | データ型 | 必須 | 入力形式 | バリデーション | 説明 |
|--------|--------|----------|------|----------|----------------|------|
| メールアドレス | email | string | ○ | テキスト（email） | メール形式 | 注文に紐づくメールアドレス |

## 表示項目

| 項目名 | 表示形式 | 説明 |
|--------|----------|------|
| ヘッダータイトル | テキスト | 「メールアドレス編集」 |
| 現在のメールアドレス | テキスト入力 | 初期値として現在のメールアドレスを表示 |

## イベント仕様

### 1-メールアドレス入力

メールアドレスフィールドに入力があった場合：
- 入力値をフォーム状態に保存
- Zodによるリアルタイムバリデーション（メール形式チェック）

### 2-保存ボタン押下

保存ボタンが押下された場合：
1. フォームバリデーションを実行
2. `useUpdateOrder`フックを使用してAPI呼び出し
3. APIエンドポイント：`POST /admin/orders/:id`
4. リクエストボディ：`{ email }`
5. 成功時：トースト通知を表示し、ドロワーを閉じる
6. 失敗時：エラーメッセージをトーストで表示

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

キャンセルボタンが押下された場合：
- フォームの変更を破棄
- ドロワーを閉じて注文詳細画面に戻る

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| 保存ボタン押下 | order | UPDATE | 注文のメールアドレス更新 |

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

#### order

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| UPDATE | email | 入力されたメールアドレス | - |
| UPDATE | updated_at | 現在日時 | 自動更新 |

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 | 表示条件 |
|-------------|------|---------------|----------|
| requestSuccess | 成功 | 「メールアドレスを更新しました: {メール}」 | 更新成功時 |
| error | エラー | APIから返されたエラーメッセージ | 更新失敗時 |
| validation | エラー | 「有効なメールアドレスを入力してください」 | メール形式エラー時 |

## 例外処理

| 例外条件 | 処理内容 |
|---------|---------|
| 注文が見つからない | エラーをスローし、エラーページを表示 |
| メール形式が不正 | フォームバリデーションエラーを表示 |
| ネットワークエラー | エラートーストを表示 |

## 備考

- メールアドレスのみを更新するシンプルな画面
- 注文に紐づく顧客のメールアドレスとは独立して管理される

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | EditOrderEmailSchema | `packages/admin/dashboard/src/routes/orders/order-edit-email/components/edit-order-email-form/edit-order-email-form.tsx` | Zodスキーマ（17-19行目） |

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | OrderEditEmail | `packages/admin/dashboard/src/routes/orders/order-edit-email/order-edit-email.tsx` | 画面コンポーネント |

**主要処理フロー**:
1. **14行目**: useParamsでIDを取得
2. **14-16行目**: useOrderフックで注文データを取得
3. **28行目**: EditOrderEmailFormコンポーネントをレンダリング

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | EditOrderEmailForm | `packages/admin/dashboard/src/routes/orders/order-edit-email/components/edit-order-email-form/edit-order-email-form.tsx` | 編集フォームの実装 |

**主要処理フロー**:
- **25-30行目**: useFormによるフォーム初期化
- **32行目**: useUpdateOrderフックの取得
- **34-46行目**: フォーム送信ハンドラ

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

```
OrderEditEmail (order-edit-email.tsx)
    │
    ├─ useOrder (注文データ取得)
    │
    └─ EditOrderEmailForm (edit-order-email-form.tsx)
           │
           └─ useUpdateOrder (orders.tsx)
                  └─ sdk.admin.order.update
                         └─ POST /admin/orders/:id
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| order-edit-email.tsx | `packages/admin/dashboard/src/routes/orders/order-edit-email/order-edit-email.tsx` | ソース | 画面コンポーネント |
| edit-order-email-form.tsx | `packages/admin/dashboard/src/routes/orders/order-edit-email/components/edit-order-email-form/edit-order-email-form.tsx` | ソース | 編集フォーム |
| orders.tsx | `packages/admin/dashboard/src/hooks/api/orders.tsx` | ソース | 注文APIフック |
