# 画面設計書 9-メール確認画面

## 概要

本ドキュメントはInvenTreeシステムのメール確認画面の設計仕様を記載する。ユーザー登録時のメールアドレス確認を行うための画面である。

### 本画面の処理概要

メール確認画面は、新規ユーザー登録時に送信される確認メールのリンクからアクセスし、メールアドレスの所有権を確認するための画面である。確認キーを使用してメールアドレスを検証し、確認完了後にログイン画面へ遷移する。

**業務上の目的・背景**：ユーザー登録時に入力されたメールアドレスが実際にユーザーの管理下にあることを確認する。これにより、不正なメールアドレスでの登録を防止し、パスワードリセットなどの機能が正常に動作することを保証する。

**画面へのアクセス方法**：新規登録後に送信される確認メールに含まれるリンク（`/verify-email/:key`）をクリックしてアクセスする。

**主要な操作・処理内容**：
1. 「Verify」ボタン押下によるメールアドレス確認の実行
2. 確認完了後、ログイン画面へ遷移

**画面遷移**：
- 遷移元：確認メール内のリンク
- 遷移先：ログイン画面（確認完了後/キー無効時）

**権限による表示制御**：
- 有効な確認キーが必要
- キーが無効または未指定の場合はエラー通知を表示し、ログイン画面へ遷移

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 33 | 認証・ログイン | 主機能 | メールアドレス確認トークンの検証処理 |

## 画面種別

確認画面

## URL/ルーティング

| パス | 説明 |
|------|------|
| `/verify-email/:key` | メール確認画面 |

### URLパラメータ

| パラメータ名 | 必須 | 説明 |
|-------------|------|------|
| key | Yes | メール確認トークン（パスパラメータ） |

## 入出力項目

### 入力項目

なし（キーはURLパラメータから取得）

### 出力項目

なし

## 表示項目

| No | 項目名 | 表示条件 | 説明 |
|----|--------|----------|------|
| 1 | 画面タイトル | 常時 | "Verify Email" |
| 2 | Verifyボタン | 常時 | メール確認実行ボタン |

## イベント仕様

### 1-画面マウント時

確認キーの存在を確認する。

**処理フロー**：
1. URLパラメータからkeyを取得
2. keyが存在しない場合：
   - 「Key invalid / You need to provide a valid key.」エラー通知を表示
   - ログイン画面へ自動遷移

### 2-Verifyボタン押下

メールアドレス確認を実行する。

**処理フロー**：
1. `handleVerifyEmail`関数を呼び出し
2. `POST /api/auth/v1/auth/email/verify` APIを呼び出し（keyパラメータ付き）
3. 成功時（200レスポンス）：
   - ログイン画面へ遷移

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| メール確認成功 | email_address | UPDATE | メール確認済みフラグの更新 |
| メール確認成功 | email_confirmation | DELETE | 使用済みトークンの削除 |

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

#### email_address

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| UPDATE | verified | True | メール確認済みに更新 |
| UPDATE | verified_at | 現在日時 | 確認日時の記録 |

#### email_confirmation

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| DELETE | - | key = 使用された確認キー | 1回限りの使用 |

## メッセージ仕様

| No | メッセージID | メッセージ種別 | メッセージ内容 | 表示条件 |
|----|-------------|---------------|---------------|----------|
| 1 | key-invalid | エラー | Key invalid / You need to provide a valid key. | キー未指定時 |

## 例外処理

| No | 例外条件 | 処理内容 |
|----|----------|----------|
| 1 | キー未指定 | エラー通知を表示し、ログイン画面へ遷移 |
| 2 | キー期限切れ/無効 | API呼び出し失敗、エラーハンドリング |
| 3 | API呼び出し失敗 | 処理続行（特別なエラーハンドリングなし） |

## 備考

- 確認キーはURLのパスパラメータとして渡される（`/verify-email/:key`形式）
- キー無効時はログイン画面へ自動遷移
- 成功時は特別な成功通知を表示せず、直接ログイン画面へ遷移
- シンプルな構造で、ボタン1つのみの画面

---

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

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

### 推奨読解順序

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

メール確認に関連するデータ構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | ApiEndpoints.tsx | `src/frontend/lib/enums/ApiEndpoints.tsx` | `auth_email_verify`エンドポイント（行40） |

**読解のコツ**: メール確認APIはkeyをパラメータとして受け取ることを理解する。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | VerifyEmail.tsx | `src/frontend/src/pages/Auth/VerifyEmail.tsx` | メール確認画面のメインコンポーネント |

**主要処理フロー**:
1. **行11-13**: keyパラメータとナビゲートの取得
2. **行15-24**: キー存在確認（useEffect）
3. **行26-33**: JSX描画（Wrapper、Verifyボタン）

#### Step 3: メール確認処理関数を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | auth.tsx | `src/frontend/src/functions/auth.tsx` | `handleVerifyEmail`関数 |

**主要処理フロー**:
- **行647-661**: `handleVerifyEmail`関数
  - 行652-654: POST auth_email_verifyエンドポイント呼び出し
  - 行655-658: 成功時のログイン画面遷移

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

```
VerifyEmail.tsx (エントリーポイント)
    │
    ├─ useParams() → key取得
    │
    ├─ useNavigate()
    │
    ├─ useEffect() [キー確認]
    │      └─ keyがない場合
    │             ├─ notifications.show (エラー)
    │             └─ navigate('/login')
    │
    ├─ Wrapper (titleText="Verify Email")
    │      │
    │      └─ Button (Verify)
    │             └─ handleVerifyEmail(key, navigate)
    │                    ├─ POST auth/v1/auth/email/verify
    │                    │      └─ { key: key }
    │                    │
    │                    └─ 成功 (200): navigate('/login')
    │
    └─ Layout.tsx (Wrapper)
```

### データフロー図

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

URLパラメータ (:key) ───▶ useParams()
                            │
                            └─ useEffect()
                                   │
                                   └─ keyがない場合
                                          ├─ notifications.show ──▶ エラー通知
                                          └─ navigate('/login') ──▶ ログイン画面へ遷移

Verifyボタン押下 ───────▶ handleVerifyEmail()
                            │
                            ├─ POST auth/v1/auth/email/verify
                            │      └─ { key: key }
                            │
                            └─ 成功時 (200)
                                   └─ navigate('/login') ────────▶ ログイン画面へ遷移

                                                                  [バックエンド]
                                                                       │
                                                                       ▼
                                                               メールアドレス確認済み
                                                               トークン無効化
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| VerifyEmail.tsx | `src/frontend/src/pages/Auth/VerifyEmail.tsx` | ソース | メール確認画面メインコンポーネント |
| auth.tsx | `src/frontend/src/functions/auth.tsx` | ソース | メール確認関数（handleVerifyEmail） |
| Layout.tsx | `src/frontend/src/pages/Auth/Layout.tsx` | ソース | 認証画面レイアウト |
| ApiEndpoints.tsx | `src/frontend/lib/enums/ApiEndpoints.tsx` | ソース | APIエンドポイント定義 |
| router.tsx | `src/frontend/src/router.tsx` | ソース | ルーティング定義 |
