# 画面設計書 5-メーラープレビュー一覧画面

## 概要

本ドキュメントは、Ruby on Rails フレームワークにおけるメーラープレビュー一覧画面の画面設計を定義するものである。

### 本画面の処理概要

本画面は、Action Mailerで定義されたメールプレビュークラスの一覧を表示する開発者向けデバッグ画面である。各メーラーのプレビュー名と、そのメーラーで定義されたメールアクション（メソッド）へのリンクを提供する。

**業務上の目的・背景**：メール送信機能の開発・テストにおいて、実際にメールを送信せずにメールの見た目や内容を確認するために使用される。ActionMailer::Previewサブクラスを定義することで、開発者はメールのHTML/テキスト形式をブラウザ上でプレビューできる。これにより、メールデザインの確認、多言語対応の検証、添付ファイルの確認などが効率的に行える。

**画面へのアクセス方法**：開発環境において、ブラウザで `/rails/mailers` にアクセスする。ローカルリクエストのみ許可（ただし `ActionMailer::Base.show_previews` が true の場合は許可）。

**主要な操作・処理内容**：
1. ActionMailer::Preview.allを呼び出して全プレビュークラスを取得
2. 各プレビュークラスをセクションとして表示
3. 各プレビューの持つメールアクション一覧をリンクとして表示
4. プレビュー名をクリックするとメーラー詳細画面に遷移
5. メールアクション名をクリックするとメールプレビュー画面に遷移

**画面遷移**：
- 遷移元：Railsウェルカム画面、その他の開発ツール画面
- 遷移先：メーラー詳細画面（プレビュー名クリック時）、メールプレビュー画面（メールアクション名クリック時）

**権限による表示制御**：`ActionMailer::Base.show_previews` の設定に応じてアクセス制御が変わる。falseの場合はローカルリクエストのみ許可。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 9 | Action Mailer | 主機能 | ActionMailer::Preview.allによる全プレビュークラスの取得 |
| 2 | Railties | 補助機能 | MailersControllerによるプレビュー一覧の制御 |
| 5 | Action View | 補助機能 | プレビュー一覧のHTML描画処理 |

## 画面種別

一覧画面（メーラープレビュー一覧）

## URL/ルーティング

| HTTP メソッド | URL パターン | コントローラー#アクション |
|--------------|--------------|--------------------------|
| GET | /rails/mailers | rails/mailers#index |

## 入出力項目

本画面は表示専用であり、ユーザーからの入力項目は存在しない。

### 出力項目

| 項目名 | 表示形式 | 説明 |
|--------|----------|------|
| ページタイトル | h1要素 | "Action Mailer Previews" |
| プレビュー名 | h3要素（リンク） | メーラー詳細画面へのリンク |
| メールアクション一覧 | ul/li要素（リンク） | メールプレビュー画面へのリンク |

## 表示項目

| No | 項目ID | 項目名 | データ型 | 取得元 | 備考 |
|----|--------|--------|----------|--------|------|
| 1 | page_title | ページタイトル | String | @page_title | "Action Mailer Previews" |
| 2 | preview_name | プレビュー名 | String | preview.preview_name | プレビュークラス名（titleize済み） |
| 3 | email_action | メールアクション名 | String | preview.emails | プレビューで定義されたメソッド名 |

## イベント仕様

### 1-プレビュー名クリック

**トリガー**: プレビュー名（h3タイトル）をクリック

**処理内容**:
1. クリックされたプレビューの詳細画面に遷移

**遷移先**: /rails/mailers/preview/{preview_name}（メーラー詳細画面）

### 2-メールアクション名クリック

**トリガー**: メールアクション名（リストアイテム）をクリック

**処理内容**:
1. クリックされたメールアクションのプレビュー画面に遷移

**遷移先**: /rails/mailers/preview/{preview_name}/{email_action}（メールプレビュー画面）

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

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

本画面はデータベースアクセスを行わない。

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| - | - | - | データベースアクセスなし |

## メッセージ仕様

| メッセージID | メッセージ種別 | 表示条件 | メッセージ内容 |
|-------------|---------------|---------|--------------|
| MSG-001 | 情報 | プレビューが定義されていない場合 | "You have not defined any Action Mailer Previews." |
| MSG-002 | リンク | プレビューが定義されていない場合 | Action Mailer Basicsガイドへのリンク |

## 例外処理

| 例外条件 | 動作 |
|---------|------|
| リモートからのアクセス（show_previews=false時） | 403 Forbiddenエラーを返却 |
| プレビューが未定義 | ガイダンスメッセージを表示 |

## 備考

- 本画面は主に開発環境で使用される
- ActionMailer::Base.show_previews設定により、本番環境でも表示可能にできる
- プレビュークラスはtest/mailers/previewsディレクトリに配置されるのが慣例
- 各プレビュークラスはActionMailer::Previewを継承する必要がある
- Content-Security-Policyはこの画面群で無効化されている（content_security_policy(false)）

---

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

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

### 推奨読解順序

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

プレビュークラスの構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | preview.rb | `actionmailer/lib/action_mailer/preview.rb` | ActionMailer::Previewクラスの構造を理解する |

**読解のコツ**:
- `Preview.all` クラスメソッド: すべてのプレビュークラスを取得
- `preview_name` メソッド: プレビューの識別名を返却
- `emails` メソッド: プレビュー可能なメールアクション一覧を返却

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

コントローラーアクションの処理フローを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | mailers_controller.rb | `railties/lib/rails/mailers_controller.rb` | indexアクションの実装を理解する |

**主要処理フロー**:
1. **9行目**: around_action :set_locale - ロケール設定
2. **10行目**: before_action :find_preview - プレビュー検索（preview/downloadのみ）
3. **11行目**: before_action :require_local! - ローカルアクセス制限（show_previews時は除外）
4. **15行目**: content_security_policy(false) - CSP無効化
5. **17-20行目**: `index` アクション - 全プレビューを取得

#### Step 3: ビューテンプレートを理解する

HTML描画の仕組みを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | index.html.erb | `railties/lib/rails/templates/rails/mailers/index.html.erb` | テンプレートの構造を理解する |

**主要処理フロー**:
- **1行目**: ページタイトル（@page_title）の表示
- **3-11行目**: プレビューがある場合のループ処理
- **4-5行目**: プレビュー名のリンク生成
- **6-9行目**: メールアクション一覧のリンク生成
- **12-15行目**: プレビューがない場合のガイダンス表示

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

```
ブラウザリクエスト (GET /rails/mailers)
    │
    ├─ before_action :require_local! (unless show_previews?)
    │      └─ ローカルIPアドレスチェック
    │
    └─ Rails::MailersController#index
           │
           ├─ ActionMailer::Preview.all 呼び出し
           │      │
           │      └─ 全プレビュークラスを収集
           │             │
           │             └─ 各 Preview サブクラス
           │                    ├─ preview_name
           │                    └─ emails
           │
           └─ index.html.erb テンプレート描画
                  │
                  ├─ @page_title 表示
                  │
                  └─ @previews ループ
                         │
                         ├─ プレビュー名リンク生成
                         │      └─ url_for(controller: "rails/mailers", action: "preview", path: preview_name)
                         │
                         └─ メールアクションリンク生成
                                └─ url_for(controller: "rails/mailers", action: "preview", path: "#{preview_name}/#{email}")
```

### データフロー図

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

HTTPリクエスト ──▶ MailersController#index
(GET /rails/mailers)
        │
        │ アクセス権チェック
        │ (show_previews? または require_local!)
        │
        └──▶ ActionMailer::Preview.all
                    │
                    ├─ test/mailers/previews/ スキャン
                    │
                    └─ Preview サブクラス一覧取得
                           │
                           ├─ preview_name 取得
                           └─ emails 取得
                                                              ↓
                                                    HTML ページ
                                                    (index.html.erb)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| mailers_controller.rb | `railties/lib/rails/mailers_controller.rb` | コントローラー | メーラープレビュー画面群のアクション定義 |
| index.html.erb | `railties/lib/rails/templates/rails/mailers/index.html.erb` | テンプレート | プレビュー一覧の描画テンプレート |
| preview.rb | `actionmailer/lib/action_mailer/preview.rb` | ソース | ActionMailer::Previewクラス定義 |
| application_controller.rb | `railties/lib/rails/application_controller.rb` | コントローラー | 親クラス、require_local!定義 |
