# 画面設計書 107-プロフィール編集画面

## 概要

本ドキュメントは、Medusa Admin Dashboard におけるプロフィール編集画面の設計仕様を定義する。

### 本画面の処理概要

プロフィール編集画面は、ログイン中の管理者ユーザーが自身のプロフィール情報を編集するためのドロワー形式の画面である。

**業務上の目的・背景**：管理者は自身の名前や表示言語を変更する必要がある場合がある。この画面により、ログインユーザーが自分のプロフィール情報（名、姓、言語設定）を更新でき、特に言語設定の変更はダッシュボード全体の表示言語に即座に反映される。

**画面へのアクセス方法**：プロフィール詳細画面（/settings/profile）のアクションメニューから「編集」を選択してアクセスする。

**主要な操作・処理内容**：
1. 名（First Name）の編集
2. 姓（Last Name）の編集
3. 表示言語の選択
4. 変更の保存

**画面遷移**：
- 遷移元：プロフィール詳細画面
- 遷移先：保存成功時はプロフィール詳細画面に戻る

**権限による表示制御**：認証済みの管理者ユーザーのみアクセス可能。自分自身のプロフィールのみ編集可能。

## 関連機能

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

## 画面種別

編集（モーダル/ドロワー形式）

## URL/ルーティング

- パス: `/settings/profile/edit`

## 入出力項目

| 項目名 | 項目ID | 入力/出力 | 必須 | データ型 | バリデーション | 備考 |
|--------|--------|----------|------|---------|---------------|------|
| 名 | first_name | 入力 | 任意 | string | - | オプション項目 |
| 姓 | last_name | 入力 | 任意 | string | - | オプション項目 |
| 言語 | language | 入力 | 必須 | string | - | Selectで選択 |

## 表示項目

| 項目名 | データソース | 表示形式 | 備考 |
|--------|-------------|---------|------|
| ヘッダータイトル | 固定値 | テキスト | 「プロフィール編集」 |
| 言語ヒント | 固定値 | テキスト | 言語設定の説明テキスト |

## イベント仕様

### 1-言語選択

- トリガー：言語Selectで値を変更
- 処理内容：フォーム状態を更新
- 状態変化：選択された言語が表示される

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

- トリガー：「保存」ボタンをクリック
- 処理内容：
  1. フォームバリデーション実行
  2. ユーザー更新APIを呼び出し（useUpdateUser）- 名と姓の更新
  3. 言語設定を変更（i18n.changeLanguage）
  4. 成功時：トースト通知を表示し、ドロワーを閉じる
  5. 失敗時：エラートースト通知を表示
- 画面遷移：保存成功時はプロフィール詳細画面に戻る

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

- トリガー：「キャンセル」ボタンをクリック
- 処理内容：ドロワーを閉じる
- 画面遷移：プロフィール詳細画面に戻る

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| 保存ボタン押下 | user | UPDATE | ユーザー情報（名、姓）を更新 |

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

#### user

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| UPDATE | first_name | フォーム入力値 | 名 |
| UPDATE | last_name | フォーム入力値 | 姓 |

※ 言語設定はデータベースに保存されず、ブラウザのローカルストレージで管理される

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 | 表示条件 |
|-------------|------|---------------|---------|
| profile.toast.edit | 成功 | プロフィールが正常に更新されました | プロフィール更新成功時 |
| (APIエラー) | エラー | エラーメッセージ（API応答） | API呼び出し失敗時 |

## 例外処理

| 例外条件 | 処理内容 | ユーザーへの通知 |
|---------|---------|----------------|
| ユーザー情報取得失敗 | エラーをスロー | エラー画面表示 |
| API通信エラー | 処理を中断 | エラートースト表示 |

## 備考

- ドロワー（RouteDrawer）形式でサイドパネルとして表示
- zodによるスキーマバリデーション（EditProfileSchema）を実装
- react-hook-formによるフォーム管理
- 言語設定はi18n.changeLanguageで即座に反映（ページリロード不要）
- 言語オプションはlanguages配列から取得し、display_nameでソートして表示
- useUpdateUserで名と姓を更新後、changeLanguageで言語を更新するという2段階処理

---

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

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

### 推奨読解順序

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

プロフィール編集のバリデーションスキーマを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | edit-profile-form.tsx | `packages/admin/dashboard/src/routes/profile/profile-edit/components/edit-profile-form/edit-profile-form.tsx` | 20-25行目のEditProfileSchemaでバリデーションルールを確認 |

**読解のコツ**: first_nameとlast_nameはz.string().optional()でオプション、languageはz.string()で必須。

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

画面のエントリーポイントとデータ取得ロジックを確認。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | profile-edit.tsx | `packages/admin/dashboard/src/routes/profile/profile-edit/profile-edit.tsx` | 画面構成とデータ取得フローを確認 |

**主要処理フロー**:
1. **8行目**: useMeでログインユーザーデータを取得
2. **10行目**: useTranslationでt関数を取得
3. **12-14行目**: エラー処理
4. **16-25行目**: RouteDrawerでドロワー表示、EditProfileFormをレンダリング

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

フォームの実装詳細を確認。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | edit-profile-form.tsx | `packages/admin/dashboard/src/routes/profile/profile-edit/components/edit-profile-form/edit-profile-form.tsx` | フォーム実装、言語変更処理、API呼び出しを確認 |

**主要処理フロー**:
- **31-39行目**: useFormでフォーム初期化（ユーザー情報とi18n.languageをデフォルト値に設定）
- **41-43行目**: changeLanguage関数でi18nの言語を変更
- **45-47行目**: languagesをdisplay_nameでソート
- **49行目**: useUpdateUserで更新mutation取得
- **51-69行目**: handleSubmitでAPI呼び出し（名・姓）と言語変更を実行
- **76-103行目**: 名と姓の入力フィールド
- **104-147行目**: 言語選択フィールド（Select）

#### Step 4: API hooks を理解する

APIとの通信処理を確認。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | users.tsx | `packages/admin/dashboard/src/hooks/api/users.tsx` | 104-127行目のuseUpdateUserでユーザー更新APIの呼び出し方法とキャッシュ無効化を確認 |

**主要処理フロー**:
- **115行目**: sdk.admin.user.updateでAPI呼び出し
- **116-121行目**: 成功時のキャッシュ無効化（ユーザー詳細、一覧、me）

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

```
ProfileEdit (profile-edit.tsx)
    │
    ├─ useMe (users.tsx)
    │      └─ sdk.admin.user.me
    │
    └─ EditProfileForm (edit-profile-form.tsx)
           │
           ├─ useUpdateUser (users.tsx)
           │      └─ sdk.admin.user.update
           │
           └─ i18n.changeLanguage
```

### データフロー図

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

(認証セッション) ───▶ useMe ───▶ user データ
         │                          │
         │                          ▼
         │              getDefaultValues ───▶ フォーム初期値
         │                                    (first_name, last_name, language)
         │
         ▼
保存ボタン ─────────┬─▶ useUpdateUser ───▶ 名・姓更新
                   │
                   └─▶ changeLanguage ───▶ 言語設定変更
                                                │
                                                ▼
                                        プロフィール詳細画面に戻る
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| profile-edit.tsx | `packages/admin/dashboard/src/routes/profile/profile-edit/profile-edit.tsx` | ソース | 画面エントリーポイント |
| edit-profile-form.tsx | `packages/admin/dashboard/src/routes/profile/profile-edit/components/edit-profile-form/edit-profile-form.tsx` | ソース | フォーム実装、バリデーション、API呼び出し |
| users.tsx | `packages/admin/dashboard/src/hooks/api/users.tsx` | ソース | ユーザーAPI hooks |
| languages.ts | `packages/admin/dashboard/src/i18n/languages.ts` | ソース | 言語定義 |
| index.ts | `packages/admin/dashboard/src/routes/profile/profile-edit/index.ts` | ソース | エクスポート定義 |
