# 画面設計書 16-アカウント設定画面

## 概要

本ドキュメントは、Payload CMSの管理画面における「アカウント設定画面」の設計仕様を定義するものである。ログイン中ユーザーの情報編集とシステム設定を行う画面である。

### 本画面の処理概要

アカウント設定画面は、現在ログイン中のユーザーが自身のプロフィール情報を編集し、管理画面のテーマ設定や言語設定などのシステムプリファレンスを管理するための画面である。

**業務上の目的・背景**：CMSを使用する各ユーザーは、自身のメールアドレス、パスワード、表示名などのプロフィール情報を更新する必要がある。また、管理画面のテーマ（ライト/ダーク）や表示言語などの個人設定をカスタマイズすることで、より快適な作業環境を構築できる。この画面は、ユーザーのセルフサービス管理を可能にし、管理者の負担を軽減する。

**画面へのアクセス方法**：管理画面のヘッダーにあるユーザーアイコン/名前をクリック、またはURLで `/{admin}/account` に直接アクセスすることで表示される。

**主要な操作・処理内容**：
1. ユーザープロフィール情報の編集（メールアドレス、表示名等）
2. パスワードの変更
3. テーマ設定の切り替え（ライト/ダーク/システム連動）
4. 表示言語の変更
5. プリファレンスのリセット
6. カスタムユーザーフィールドの編集（設定されている場合）

**画面遷移**：
- 遷移元：ダッシュボード画面、ヘッダーメニュー
- 遷移先：ダッシュボード画面（保存後）、ログイン画面（ログアウト）

**権限による表示制御**：ログイン中のユーザーは自身のアカウント情報を編集可能。管理者権限がなくても自身のアカウントにはアクセスできる。ただし、一部のフィールドは管理者のみ編集可能な場合がある（ロール変更など）。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 6 | ユーザー認証 | 主機能 | ログインユーザー情報の編集・更新 |
| 3 | フィールドシステム | 補助機能 | ユーザー情報フォームのフィールド構築 |
| 51 | 翻訳システム | 補助機能 | 言語設定の変更 |
| 61 | プリファレンス | API連携 | テーマ設定、UI設定の保存・読込 |

## 画面種別

編集

## URL/ルーティング

`/{adminRoute}/account`

パラメータ:
- `{adminRoute}`: 管理画面のベースパス（デフォルト: `/admin`）

## 入出力項目

| 項目名 | 入力/出力 | データ型 | 必須 | 説明 |
|--------|----------|---------|------|------|
| email | 入力 | string | Yes | ユーザーのメールアドレス |
| password | 入力 | string | No | 新しいパスワード（変更時のみ） |
| passwordConfirm | 入力 | string | No | パスワード確認（変更時のみ） |
| name | 入力 | string | No | 表示名（設定による） |
| language | 入力 | string | No | 表示言語 |
| theme | 入力 | string | No | テーマ設定（light/dark/auto） |
| カスタムフィールド | 入力 | various | - | ユーザーコレクションに定義されたカスタムフィールド |
| userData | 出力 | object | - | 現在のユーザーデータ |

## 表示項目

| 項目名 | データ型 | 説明 |
|--------|---------|------|
| メールアドレス | EmailField | ユーザーのメールアドレス |
| パスワード | PasswordField | パスワード変更フィールド |
| ユーザーフィールド | various | ユーザーコレクションのカスタムフィールド |
| 言語選択 | Select | 表示言語セレクター |
| テーマ切り替え | Toggle | ライト/ダーク/自動の切り替え |
| プリファレンスリセット | Button | 全プリファレンスをリセットするボタン |

## イベント仕様

### 1-アカウント情報表示

画面表示時にログインユーザーの情報を取得して表示する。

**処理フロー**：
1. `req.user` からログインユーザーIDを取得
2. `getDocumentData()` でユーザーデータを取得
3. `getDocPreferences()` でドキュメントプリファレンスを取得
4. `buildFormState()` でフォーム初期状態を構築
5. `getVersions()` でバージョン情報を取得（versions有効時）
6. フォームをレンダリング

### 2-アカウント情報更新

フォームの内容を保存する。

**処理フロー**：
1. フォームデータをバリデーション
2. `payload.update()` でユーザードキュメントを更新
3. 成功時は認証状態を更新
4. 成功メッセージを表示

### 3-テーマ切り替え

ライト/ダーク/自動モードを切り替える。

**処理フロー**：
1. ToggleThemeコンポーネントでテーマを選択
2. プリファレンスを保存
3. 即時にUIに反映

### 4-言語変更

表示言語を変更する。

**処理フロー**：
1. LanguageSelectorで言語を選択
2. プリファレンスを保存
3. ページを再読み込みして言語を適用

### 5-プリファレンスリセット

全てのユーザープリファレンスをリセットする。

**処理フロー**：
1. リセットボタンをクリック
2. 確認ダイアログを表示
3. プリファレンスを削除
4. ページを再読み込み

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| アカウント情報表示 | {userSlug} | SELECT | ログインユーザーのデータ取得 |
| アカウント情報更新 | {userSlug} | UPDATE | ユーザーデータの更新 |
| プリファレンス保存 | payload-preferences | INSERT/UPDATE | ユーザー設定の保存 |
| プリファレンスリセット | payload-preferences | DELETE | ユーザー設定の削除 |

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

#### {userSlug}（ユーザーコレクション）

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | - | WHERE id = {userId} | ログインユーザー取得 |
| UPDATE | email, name, 他 | フォーム入力値 | プロフィール更新 |
| UPDATE | password | ハッシュ化された新パスワード | パスワード変更時 |

#### payload-preferences

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| INSERT/UPDATE | key, value | 設定キーと値 | プリファレンス保存 |
| DELETE | - | WHERE user = {userId} | プリファレンスリセット |

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 | 表示条件 |
|-------------|------|---------------|----------|
| account.saved | 成功 | アカウント情報を保存しました | 保存成功時 |
| account.saveError | エラー | アカウント情報の保存に失敗しました | 保存失敗時 |
| account.passwordMismatch | エラー | パスワードが一致しません | パスワード確認不一致時 |
| preferences.reset | 成功 | プリファレンスをリセットしました | リセット成功時 |
| general.payloadSettings | ラベル | Payload設定 | 設定セクションタイトル |
| general.language | ラベル | 言語 | 言語選択ラベル |

## 例外処理

| 例外状態 | 対応 |
|---------|------|
| ユーザーが見つからない | notFound()を呼び出し |
| ログインしていない | ログイン画面へリダイレクト |
| 更新権限がない | エラーメッセージを表示 |
| バリデーションエラー | フィールドにエラーメッセージを表示 |

## 備考

- アカウント画面はユーザーコレクションの編集画面を再利用している
- `config.admin.user` でユーザーコレクションのスラッグを指定
- `AfterFields` スロットにSettings（テーマ・言語設定）コンポーネントを挿入
- `theme === 'all'` の場合のみテーマ切り替えUIが表示される
- EditViewをフォールバックとして使用し、カスタムコンポーネントをサポート
- DocumentInfoProviderでドキュメント情報を提供
- HydrateAuthProviderで認証状態を同期

---

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

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

### 推奨読解順序

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

アカウント設定画面で扱うデータ構造の理解が重要である。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | index.tsx | `packages/next/src/views/Account/index.tsx` | AccountView関数のprops構造（行20-32） |
| 1-2 | Settings/index.tsx | `packages/next/src/views/Account/Settings/index.tsx` | Settings propsの構造（行14-20） |

**読解のコツ**: アカウント画面はユーザーコレクションのドキュメント編集画面を拡張している。`req.user` が編集対象のドキュメントとなる。

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

アカウント設定画面のエントリーポイントとなるファイルを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | index.tsx | `packages/next/src/views/Account/index.tsx` | AccountView関数の構造 |

**主要処理フロー**:
1. **行20-32**: propsの分解（initPageResult等）
2. **行34-38**: config.admin.user からユーザーコレクション設定取得
3. **行40**: collectionConfigの取得
4. **行42-51**: getDocumentData() でユーザーデータ取得
5. **行57-63**: getDocPreferences() でプリファレンス取得
6. **行66-77**: getDocumentPermissions() で権限取得
7. **行79-92**: buildFormState() でフォーム状態構築
8. **行94-100**: getIsLocked() でロック状態確認
9. **行103-112**: getVersions() でバージョン情報取得
10. **行114-176**: DocumentInfoProvider + EditView でレンダリング

#### Step 3: 設定コンポーネントを理解する

Settings（テーマ・言語設定）コンポーネントを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Settings/index.tsx | `packages/next/src/views/Account/Settings/index.tsx` | Settingsコンポーネント |

**主要処理フロー**:
- **行27-28**: 言語選択UI（LanguageSelector）
- **行31**: テーマ切り替えUI（ToggleTheme）、theme === 'all' の場合のみ表示
- **行32**: プリファレンスリセット（ResetPreferences）

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

```
AccountView (Account/index.tsx)
    │
    ├─ collectionConfig取得
    │   └─ payload.collections[userSlug].config
    │
    ├─ getDocumentData() - ユーザーデータ取得
    │   └─ id: user.id, collectionSlug: userSlug
    │
    ├─ getDocPreferences() - プリファレンス取得
    │
    ├─ getDocumentPermissions() - 権限取得
    │
    ├─ buildFormState() - フォーム状態構築
    │   └─ operation: 'update'
    │
    ├─ getIsLocked() - ロック状態確認
    │
    ├─ getVersions() - バージョン情報取得
    │
    └─ DocumentInfoProvider
           │
           ├─ AfterFields: Settings
           │      ├─ LanguageSelector - 言語選択
           │      ├─ ToggleTheme - テーマ切り替え
           │      └─ ResetPreferences - リセット
           │
           ├─ DocumentHeader - ヘッダー
           │
           ├─ HydrateAuthProvider - 認証同期
           │
           └─ EditView (Fallback) - 編集フォーム
```

### データフロー図

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

req.user ─────────────▶ AccountView ───▶ アカウント編集フォーム
  (ログインユーザー)          │
                              ├─▶ getDocumentData()
                              │      └─▶ ユーザードキュメント
                              │
                              ├─▶ buildFormState()
                              │      └─▶ フォーム初期状態
                              │
                              ├─▶ Settings (AfterFields)
                              │      ├─▶ LanguageSelector
                              │      ├─▶ ToggleTheme
                              │      └─▶ ResetPreferences
                              │
                              └─▶ EditView
                                     └─▶ ユーザーフィールドフォーム
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| index.tsx | `packages/next/src/views/Account/index.tsx` | ソース | アカウント画面のサーバーコンポーネント |
| index.client.tsx | `packages/next/src/views/Account/index.client.tsx` | ソース | クライアント側コンポーネント |
| Settings/index.tsx | `packages/next/src/views/Account/Settings/index.tsx` | ソース | 設定セクション |
| LanguageSelector.tsx | `packages/next/src/views/Account/Settings/LanguageSelector.tsx` | ソース | 言語選択コンポーネント |
| ToggleTheme/index.tsx | `packages/next/src/views/Account/ToggleTheme/index.tsx` | ソース | テーマ切り替えコンポーネント |
| ResetPreferences/index.tsx | `packages/next/src/views/Account/ResetPreferences/index.tsx` | ソース | プリファレンスリセット |
| EditView | `packages/next/src/views/Edit/index.tsx` | ソース | 編集ビューコンポーネント |
| DocumentInfoProvider | `packages/ui/src/providers/DocumentInfo/index.tsx` | ソース | ドキュメント情報プロバイダー |
