# 画面設計書 20-メールレイアウト

## 概要

本ドキュメントは、LaravelフレームワークにおけるHTMLメールレイアウトコンポーネントの設計仕様を定義する。

### 本画面の処理概要

メールレイアウトは、LaravelのMarkdownメールおよびMailableクラスで使用されるHTMLメールの基本構造を提供するBladeコンポーネントである。XHTML 1.0 Transitional準拠のHTML構造を持ち、広範囲のメールクライアント（Gmail、Outlook、Apple Mail等）との互換性を確保する。CSSインラインスタイルへの変換やMarkdownパースと連携して、リッチなHTMLメールを生成する。

**業務上の目的・背景**：ビジネスアプリケーションでは、ユーザーへの通知、パスワードリセット、注文確認など、様々な場面でメール送信が必要となる。一貫したブランディングとプロフェッショナルな外観を維持しつつ、多様なメールクライアントで正しく表示されるHTMLメールを効率的に作成するため、共通レイアウトが必要である。

**画面へのアクセス方法**：Markdownメールで`<x-mail::layout>`コンポーネントとして使用される。または`mail::message`ビュー経由で自動的に適用される。Mailableクラスで`markdown()`メソッドを使用する場合に自動的にこのレイアウトが適用される。

**主要な操作・処理内容**：
1. HTML構造の定義 - XHTML 1.0 Transitional DTDに準拠した文書構造
2. メタデータの設定 - viewport、charset、color-scheme設定
3. レスポンシブ対応 - メディアクエリによるモバイル最適化
4. スロットベースのコンテンツ挿入 - header、body、subcopy、footerの各領域
5. Markdownパース - `Illuminate\Mail\Markdown::parse()`による本文変換
6. CSSインライン化 - TijsVerkoyen\CssToInlineStylesによるスタイル適用

**画面遷移**：メール内のリンク（ボタン等）クリックでWebアプリケーションへ遷移する。

**権限による表示制御**：メール送信時の宛先や条件により、異なる内容のメールが生成される。レイアウト自体には権限制御機能はない。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 28 | メール管理 | 主機能 | HTMLメールの共通レイアウト構造定義 |
| 36 | ビューファクトリ | 補助機能 | メールテンプレートの描画処理 |

## 画面種別

コンポーネント（HTMLメールレイアウトテンプレート）

## URL/ルーティング

このコンポーネントはメール生成用であり、HTTPルーティングを持たない。

## 入出力項目

| 項目名 | 型 | I/O | 説明 |
|--------|-----|-----|------|
| $slot | string | 入力 | メール本文（Markdown形式） |
| $header | string | 入力 | ヘッダースロット（オプション） |
| $subcopy | string | 入力 | サブコピースロット（オプション） |
| $footer | string | 入力 | フッタースロット（オプション） |
| $head | string | 入力 | 追加headタグ内容（オプション） |

## 表示項目

| 項目名 | 表示形式 | 説明 |
|--------|----------|------|
| HTMLヘッダー | head要素 | title、meta、style要素を含む |
| wrapper table | テーブルレイアウト | メール全体のコンテナ（100%幅） |
| content table | テーブルレイアウト | コンテンツエリア（100%幅） |
| header slot | カスタム領域 | ロゴ、アプリ名等を表示 |
| inner-body | テーブルレイアウト | 本文エリア（570px幅） |
| content-cell | td要素 | Markdown変換後の本文を表示 |
| subcopy slot | カスタム領域 | 補足情報を表示 |
| footer slot | カスタム領域 | 著作権情報等を表示 |

## イベント仕様

### 1-メール本文レンダリング

`Illuminate\Mail\Markdown::parse($slot)`によりMarkdown本文がHTMLに変換される。
- Markdownパーサー：League\CommonMark
- 対応記法：見出し、リスト、リンク、テーブル、強調等

### 2-CSSインライン化

`TijsVerkoyen\CssToInlineStyles`ライブラリによりCSSがインラインスタイルに変換される。
- テーマCSS（default.css等）が適用される
- メールクライアント互換性のために必須

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| メール生成 | - | - | レイアウト自体はDB操作を行わない |

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

メールレイアウトはデータベースの更新を行わない。

## メッセージ仕様

| 種別 | 設定キー | 取得内容 | 表示条件 |
|------|---------|----------|----------|
| 設定 | app.name | アプリケーション名 | title要素 |
| 設定 | app.locale | ロケール | html lang属性 |

## 例外処理

| 状態 | 処理内容 |
|------|----------|
| Markdownパースエラー | CommonMarkが例外をスロー |
| ビュー存在しない | ViewFactoryがViewNotFoundExceptionをスロー |

## 備考

- XHTML 1.0 Transitional DTD準拠
- メールクライアント互換性のためテーブルレイアウトを使用
- `color-scheme: light`でライトモード推奨
- レスポンシブブレークポイント：600px、500px
- inner-body幅：570px（中央揃え）
- Bladeコンポーネント構文（`<x-mail::layout>`）を使用
- テーマカスタマイズ：`vendor/mail/html/themes/`に独自CSSを配置

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Markdown.php | `src/Illuminate/Mail/Markdown.php` | HTMLメールのレンダリングフロー、テーマ適用 |
| 1-2 | Mailable.php | `src/Illuminate/Mail/Mailable.php` | MailableクラスからのMarkdownメール生成 |

**読解のコツ**: Markdown.phpのrender()メソッドがHTMLメール生成の中心。テーマCSSの適用とインライン化はここで行われる。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Markdown.php | `src/Illuminate/Mail/Markdown.php` | render()メソッド（66-113行目） |

**主要処理フロー**:
1. **68行目**: `flushFinderCache()` - ビューキャッシュのクリア
2. **75-100行目**: Blade Echo形式を変更してビューレンダリング
3. **91-93行目**: mailネームスペースをHTMLコンポーネントパスで置換
4. **102-108行目**: テーマCSSの解決
5. **110-112行目**: CSSToInlineStylesでインライン化

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | layout.blade.php | `src/Illuminate/Mail/resources/views/html/layout.blade.php` | HTMLメールの基本構造（59行） |
| 3-2 | message.blade.php | `src/Illuminate/Mail/resources/views/html/message.blade.php` | メッセージ構成（28行） |

**主要処理フロー**:
- **1行目**: DOCTYPE宣言（XHTML 1.0 Transitional）
- **2行目**: `lang="{{ str_replace('_', '-', app()->getLocale()) }}"` - ロケール設定
- **4行目**: アプリ名をtitleに設定
- **9-24行目**: レスポンシブ用メディアクエリ
- **30-56行目**: テーブルベースのレイアウト構造
- **43行目**: `Illuminate\Mail\Markdown::parse($slot)` - Markdownパース

#### Step 4: コンポーネント構造を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | header.blade.php | `src/Illuminate/Mail/resources/views/html/header.blade.php` | ヘッダーコンポーネント |
| 4-2 | footer.blade.php | `src/Illuminate/Mail/resources/views/html/footer.blade.php` | フッターコンポーネント |
| 4-3 | button.blade.php | `src/Illuminate/Mail/resources/views/html/button.blade.php` | ボタンコンポーネント |

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

```
Mailable->markdown('mail.notification')
    │
    └─ Markdown::render()
           │
           ├─ ViewFactory->replaceNamespace('mail', htmlComponentPaths())
           │
           ├─ View->make('mail.notification')->render()
           │      │
           │      └─ message.blade.php
           │             │
           │             └─ <x-mail::layout>
           │                    │
           │                    ├─ <x-slot:header>
           │                    │      └─ <x-mail::header>
           │                    │
           │                    ├─ {!! $slot !!}
           │                    │      └─ Markdown::parse()
           │                    │
           │                    ├─ <x-slot:subcopy>
           │                    │      └─ <x-mail::subcopy>
           │                    │
           │                    └─ <x-slot:footer>
           │                           └─ <x-mail::footer>
           │
           ├─ View->make('mail::themes.default')->render()
           │      └─ CSS取得
           │
           └─ CssToInlineStyles->convert(html, css)
                  └─ インラインスタイル適用済みHTML
```

### データフロー図

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

Mailable              ──▶ Markdown::render()         ──▶ HTMLメール
  - markdown view          │                             <!DOCTYPE html>
  - data                   ├─ Bladeコンパイル             <html>
                           │   message.blade.php           <head>
$slot (Markdown)      ──▶  │                               <style>...
                           ├─ layout.blade.php              </style>
$header              ──▶   │   構造生成                   </head>
                           │                             <body>
$footer              ──▶   ├─ Markdown::parse()           <table class="wrapper">
                           │   MD→HTML変換                  <tr><td>
$subcopy             ──▶   │                                 {header}
                           ├─ テーマCSS読込                   {body}
theme.css            ──▶   │                                 {subcopy}
                           │                                 {footer}
                           └─ CssToInlineStyles            </td></tr>
                               インライン化               </table>
                                                          </body>
                                                          </html>
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| layout.blade.php | `src/Illuminate/Mail/resources/views/html/layout.blade.php` | テンプレート | HTMLメール基本構造 |
| message.blade.php | `src/Illuminate/Mail/resources/views/html/message.blade.php` | テンプレート | メッセージ構成 |
| header.blade.php | `src/Illuminate/Mail/resources/views/html/header.blade.php` | テンプレート | ヘッダー部品 |
| footer.blade.php | `src/Illuminate/Mail/resources/views/html/footer.blade.php` | テンプレート | フッター部品 |
| button.blade.php | `src/Illuminate/Mail/resources/views/html/button.blade.php` | テンプレート | ボタン部品 |
| panel.blade.php | `src/Illuminate/Mail/resources/views/html/panel.blade.php` | テンプレート | パネル部品 |
| table.blade.php | `src/Illuminate/Mail/resources/views/html/table.blade.php` | テンプレート | テーブル部品 |
| subcopy.blade.php | `src/Illuminate/Mail/resources/views/html/subcopy.blade.php` | テンプレート | サブコピー部品 |
| Markdown.php | `src/Illuminate/Mail/Markdown.php` | ソース | Markdownレンダラー |
| Mailable.php | `src/Illuminate/Mail/Mailable.php` | ソース | メール送信基底クラス |
| MailServiceProvider.php | `src/Illuminate/Mail/MailServiceProvider.php` | ソース | サービス登録 |
