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

## 概要

本ドキュメントは、Chatwootアプリケーションのメール確認画面に関する設計書です。ユーザー登録時に送信される確認メールのリンクから遷移し、メールアドレスの確認を行う機能を提供する画面について記述しています。

### 本画面の処理概要

メール確認画面は、ユーザー登録後に送信される確認メールのリンクからアクセスし、メールアドレスの有効性を検証する画面です。確認トークンを検証し、メールアドレスの確認を完了します。

**業務上の目的・背景**：メールアドレスの所有権を確認することで、不正なアカウント作成を防止し、重要な通知が正しいメールアドレスに届くことを保証します。本画面は、確認トークンの検証を自動的に行い、ユーザーの手間を最小限に抑えながらセキュリティを確保します。

**画面へのアクセス方法**：ユーザー登録時に送信される確認メールに含まれるリンクからアクセスします。URLには `confirmation_token` クエリパラメータが含まれています。

**主要な操作・処理内容**：
1. 画面表示時に確認トークンを自動検証する
2. 検証完了後、ダッシュボードホーム画面にリダイレクトする

**画面遷移**：
- 遷移元：確認メールのリンク
- 遷移先：ダッシュボードホーム画面（検証成功・失敗ともに）

**権限による表示制御**：
- セッションを無視するメタ情報（`ignoreSession: true`）が設定されている
- 確認トークンがない場合もダッシュボードにリダイレクト

## 関連機能

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

## 画面種別

処理中（確認処理）

## URL/ルーティング

| パス | ルート名 | 説明 |
|------|----------|------|
| `/app/auth/confirmation` | `auth_confirmation` | メール確認画面 |

### クエリパラメータ

| パラメータ | 型 | 説明 |
|-----------|-----|------|
| `confirmation_token` | String | メール確認トークン（必須） |
| `config` | String | 設定情報 |
| `route_url` | String | リダイレクトURL |

### ルートメタ情報

| メタキー | 値 | 説明 |
|---------|-----|------|
| `ignoreSession` | `true` | セッション状態を無視 |

## 入出力項目

### 入力項目

本画面ではユーザーによる入力項目はありません。確認トークンはURLパラメータから自動取得されます。

### 出力項目

本画面では処理中の表示のみで、成功・失敗ともにダッシュボードにリダイレクトされます。

## 表示項目

| 項目名 | 説明 | 表示条件 |
|--------|------|----------|
| ローディングスピナー | 処理中を示すスピナー | 常時 |
| 確認中メッセージ | 「メールを確認中...」 | 常時 |

## イベント仕様

### 1-コンポーネントマウント時

**トリガー**: コンポーネントのマウント

**処理フロー**:
1. `confirmToken` メソッドを呼び出し
2. API `POST /api/v1/auth/confirmation` に確認トークンを送信
3. レスポンスに応じた処理:
   - 成功: 認証情報を設定し、ダッシュボードにリダイレクト
   - 失敗: ダッシュボードにリダイレクト（エラー表示なし）

**データフロー**:
```
[コンポーネントマウント]
    │
    ▼
[confirmToken()]
    │
    ▼
[verifyPasswordToken API呼び出し]
    │
    ├─ 成功 ─▶ [認証情報設定] → [ダッシュボードへリダイレクト]
    │
    └─ 失敗 ─▶ [ダッシュボードへリダイレクト]
```

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| 確認成功 | users | UPDATE | `confirmed_at`の設定、確認トークンのクリア |

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

#### users

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| UPDATE | confirmed_at | 現在時刻 | 確認完了日時 |
| UPDATE | confirmation_token | NULL | トークンクリア |
| UPDATE | updated_at | 現在時刻 | 更新日時 |

## メッセージ仕様

| メッセージID | メッセージ種別 | メッセージ内容 | 表示条件 |
|-------------|---------------|---------------|----------|
| CONFIRM_EMAIL | 情報 | メールを確認中... | 処理中 |

## 例外処理

| 例外条件 | 状態・動作 |
|---------|----------|
| 確認トークンなし | ダッシュボードにリダイレクト |
| 確認トークン無効 | ダッシュボードにリダイレクト |
| 確認トークン期限切れ | ダッシュボードにリダイレクト |
| ネットワークエラー | ダッシュボードにリダイレクト |
| サーバーエラー（500系） | ダッシュボードにリダイレクト |

## 備考

- 確認処理は自動的に実行され、ユーザー操作は不要
- 成功・失敗に関わらず、処理完了後はダッシュボードにリダイレクト
- エラー時もエラーメッセージは表示されない（ユーザー体験を考慮）
- `ignoreSession`メタ情報により、既存のセッション状態は無視される
- verifyPasswordTokenという関数名だが、実際にはメール確認トークンの検証を行う

---

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

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

### 推奨読解順序

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

メール確認処理で扱われるデータ構造を理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | auth.js | `app/javascript/v3/api/auth.js` | verifyPasswordToken関数のリクエスト形式（行68-76） |

**読解のコツ**: `POST auth/confirmation` エンドポイントに対して、確認トークンを送信します。

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

処理の起点となるVueコンポーネントを特定します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Index.vue | `app/javascript/v3/views/auth/confirmation/Index.vue` | メール確認画面のメインコンポーネント |
| 2-2 | routes.js | `app/javascript/v3/views/routes.js` | ルーティング定義、`ignoreSession`メタ情報 |

**主要処理フロー**:
1. **行14-15**: `mounted`ライフサイクルフックで`confirmToken`を呼び出し
2. **行18-27**: `confirmToken`メソッドでAPI呼び出しとリダイレクト処理
3. **行20-22**: try句で成功時の認証情報設定とリダイレクト
4. **行24-26**: catch句でエラー時のリダイレクト

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

```
Index.vue (メール確認画面)
    │
    └─ mounted()
           │
           └─ confirmToken()
                  │
                  ├─ verifyPasswordToken() [auth.js]
                  │      │
                  │      └─ wootAPI.post('auth/confirmation')
                  │             │
                  │             └─ [Backend] confirmations_controller#create
                  │
                  └─ [成功/失敗] → DEFAULT_REDIRECT_URL へリダイレクト
```

### データフロー図

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

confirmationToken       ──▶   Index.vue                  ──▶   ダッシュボード
(URLパラメータ)               (mounted → confirmToken)          リダイレクト
                                  │
                                  ▼
                              verifyPasswordToken() [auth.js]
                                  │
                                  ▼
                              POST /api/v1/auth/confirmation
                              { confirmation_token }
                                  │
                                  ▼
                              [Backend]
                              confirmations_controller#create
                                  │
                         ┌────────┴────────┐
                         ▼                 ▼
                    [成功]             [失敗]
                      │                  │
                      ▼                  ▼
                認証情報保存         ダッシュボード
                ダッシュボード        リダイレクト
                リダイレクト
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Index.vue | `app/javascript/v3/views/auth/confirmation/Index.vue` | ソース | メール確認画面メインコンポーネント |
| routes.js | `app/javascript/v3/views/routes.js` | ソース | ルーティング定義 |
| auth.js | `app/javascript/v3/api/auth.js` | ソース | 認証API関数 |
| Spinner.vue | `app/javascript/shared/components/Spinner.vue` | ソース | ローディングスピナーコンポーネント |
| globals.js | `app/javascript/dashboard/constants/globals.js` | 設定 | DEFAULT_REDIRECT_URL定義 |
| en.json | `app/javascript/dashboard/i18n/locale/en/common.json` | 設定 | i18n翻訳ファイル |
