# 画面設計書 122-ユーザー編集画面

## 概要

本ドキュメントは、Medusa Admin Dashboardにおけるユーザー編集画面の設計を記述したものです。管理者ユーザーの基本情報（名前）を編集するためのモーダル形式のドロワー画面です。

### 本画面の処理概要

この画面では、管理者ユーザーの名前（姓・名）を編集できます。メールアドレスは編集対象外であり、変更されません。

**業務上の目的・背景**：ECサイト運営において、管理者の人事異動や名前変更（結婚等）に対応するため、ユーザー情報を更新する機能が必要です。この画面は、ユーザー詳細画面から呼び出される補助的なモーダル画面として、シンプルな名前変更機能を提供します。フォームバリデーションにより、入力ミスを防止し、安全な更新処理を実現します。

**画面へのアクセス方法**：ユーザー詳細画面（No.121）のアクションメニューから「編集」を選択することでアクセスします。URLパスは `/settings/users/:id/edit` の形式で、ドロワー（サイドパネル）形式で表示されます。

**主要な操作・処理内容**：
1. 名（first_name）の入力・編集
2. 姓（last_name）の入力・編集
3. 保存ボタンクリックでユーザー情報を更新
4. キャンセルボタンクリックでドロワーを閉じる

**画面遷移**：
- 遷移元：ユーザー詳細画面（No.121）
- 遷移先：保存完了後、ユーザー詳細画面へ戻る

**権限による表示制御**：認証済みの管理者ユーザーのみアクセス可能です。他のユーザーの情報も編集できます。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 62 | ユーザーCRUD | 主機能 | ユーザー情報の編集 |

## 画面種別

編集（モーダル形式）

## URL/ルーティング

`/settings/users/:id/edit`

## 入出力項目

| 項目名 | 入力/出力 | データ型 | 必須 | 説明 |
|--------|----------|----------|------|------|
| id | 入力（URLパラメータ） | string | Yes | ユーザーID |
| first_name | 入力（フォーム） | string | No | 名 |
| last_name | 入力（フォーム） | string | No | 姓 |

## 表示項目

| 項目名 | データ型 | 説明 |
|--------|----------|------|
| ヘッダータイトル | string | 「ユーザーを編集」（i18n: users.editUser） |
| 名入力フィールド | Input | first_nameを編集するための入力欄 |
| 姓入力フィールド | Input | last_nameを編集するための入力欄 |

## イベント仕様

### 1-保存ボタンクリック

保存ボタンをクリックすると、フォームのバリデーション後にユーザー情報が更新されます。

- バリデーション:
  - first_name: オプショナル（string型）
  - last_name: オプショナル（string型）
- 処理内容:
  - `POST /admin/users/:id` APIを呼び出し（useUpdateUserフック）
  - 成功時: ドロワーを閉じてユーザー詳細画面に戻る（handleSuccess()）
  - 失敗時: エラーが発生した場合のみエラーハンドリング（デフォルトの動作）

### 2-キャンセルボタンクリック

キャンセルボタンをクリックすると、変更を保存せずにドロワーを閉じます。

- 処理内容: RouteDrawer.Closeによりドロワーを閉じる

### 3-フォーム入力

キーボードショートカット（KeyboundForm）により、Enterキーでフォーム送信が可能です。

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| 画面表示 | user | SELECT | ユーザー情報の取得（フォーム初期値設定用） |
| 保存ボタン押下 | user | UPDATE | ユーザー情報の更新 |

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

#### user

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | id, email, first_name, last_name | id = URLパラメータのid | フォーム初期値設定用 |
| UPDATE | first_name | フォーム入力値 | 空文字列の場合はそのまま保存 |
| UPDATE | last_name | フォーム入力値 | 空文字列の場合はそのまま保存 |

## メッセージ仕様

| メッセージ種別 | 表示条件 | メッセージ内容（i18nキー） |
|--------------|----------|------------------------|
| ラベル | 常時 | fields.firstName, fields.lastName |
| ボタン | 常時 | actions.cancel, actions.save |
| ヘッダー | 常時 | users.editUser |

## 例外処理

| 例外条件 | 処理内容 |
|---------|---------|
| ユーザーが見つからない | エラーをスロー（isError状態）してエラーバウンダリでハンドリング |
| ローディング中 | EditUserFormコンポーネントを表示しない（条件付きレンダリング） |

## 備考

- zodResolverを使用したフォームバリデーション
- react-hook-formによるフォーム状態管理
- KeyboundFormコンポーネントによりキーボードショートカットが有効

---

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

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

### 推奨読解順序

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

まず、フォームのスキーマと送信データの構造を理解することが重要です。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | edit-user-form.tsx | `packages/admin/dashboard/src/routes/users/user-edit/components/edit-user-form/edit-user-form.tsx` | EditUserFormSchemaの定義（17-20行目） |

**読解のコツ**: zodスキーマでfirst_nameとlast_nameがオプショナル（.optional()）であることに注目してください。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | user-edit.tsx | `packages/admin/dashboard/src/routes/users/user-edit/user-edit.tsx` | RouteDrawerによるモーダル構成、useUserでのデータ取得 |

**主要処理フロー**:
1. **10行目**: useParamsでURLからユーザーIDを取得
2. **11行目**: useUserフックでユーザーデータを取得
3. **17-24行目**: RouteDrawerでドロワーUI構成、ローディング完了後にEditUserFormを表示

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | edit-user-form.tsx | `packages/admin/dashboard/src/routes/users/user-edit/components/edit-user-form/edit-user-form.tsx` | フォーム実装、バリデーション、API呼び出し |

**主要処理フロー**:
- **26-32行目**: useFormでフォーム状態を初期化（defaultValuesにユーザー情報を設定）
- **34行目**: useUpdateUserフックでミューテーション関数を取得
- **36-42行目**: handleSubmit関数で更新処理を実行
- **44-96行目**: RouteDrawer.Formでフォームをラップし、Input/Buttonコンポーネントを配置

#### Step 4: API呼び出しフックを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | users.tsx | `packages/admin/dashboard/src/hooks/api/users.tsx` | useUpdateUserフックの実装（104-127行目） |

**主要処理フロー**:
- **114-115行目**: sdk.admin.user.update()を呼び出し
- **116-122行目**: 成功時にdetail、lists、meクエリを無効化（キャッシュリフレッシュ）

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

```
UserEdit (user-edit.tsx)
    │
    ├─ useParams() → id取得
    │
    ├─ useUser(id) → hooks/api/users.tsx
    │      └─ sdk.admin.user.retrieve()
    │
    └─ RouteDrawer
           └─ EditUserForm (edit-user-form.tsx)
                  │
                  ├─ useForm() → react-hook-form
                  │      └─ zodResolver(EditUserFormSchema)
                  │
                  ├─ useUpdateUser(id) → hooks/api/users.tsx
                  │
                  └─ handleSubmit()
                         └─ mutateAsync(values)
                                └─ sdk.admin.user.update()
```

### データフロー図

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

URLパラメータ(:id) ───▶ useParams()              ───▶ id
                              │
                              ▼
                        useUser(id)              ───▶ user オブジェクト
                              │
                              ▼
user.first_name ───────▶ useForm()
user.last_name             (defaultValues設定)
                              │
                              ▼
フォーム入力 ──────────▶ handleSubmit()
(first_name, last_name)       │
                              ▼
                        useUpdateUser()
                              │
                              ▼
                        sdk.admin.user.update() ───▶ 更新されたuser
                              │
                              ▼
                        handleSuccess()         ───▶ ドロワー閉じる
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| user-edit.tsx | `packages/admin/dashboard/src/routes/users/user-edit/user-edit.tsx` | ソース | エントリーポイント、ドロワーコンテナ |
| edit-user-form.tsx | `packages/admin/dashboard/src/routes/users/user-edit/components/edit-user-form/edit-user-form.tsx` | ソース | フォームコンポーネント |
| users.tsx | `packages/admin/dashboard/src/hooks/api/users.tsx` | ソース | APIフック（useUser, useUpdateUser） |
| index.ts | `packages/admin/dashboard/src/routes/users/user-edit/index.ts` | ソース | バレルエクスポート |
| index.ts | `packages/admin/dashboard/src/routes/users/user-edit/components/edit-user-form/index.ts` | ソース | フォームコンポーネントエクスポート |
