# 画面設計書 77-通知メールテンプレート

## 概要

本ドキュメントは、Laravel フレームワークの「通知メールテンプレート」の設計書である。このテンプレートは、Laravel通知システム（Notification）のデフォルトメール形式を定義し、Markdownベースのメールコンポーネントを使用して構造化されたメールを生成する。

### 本画面の処理概要

通知メールテンプレートは、Laravel通知システムにおけるメール送信のデフォルトテンプレートである。

**業務上の目的・背景**：アプリケーションにおける様々な通知（パスワードリセット、注文確認、アカウント確認など）をユーザーにメールで送信する際、一貫したデザインと構造を持つメールを簡単に作成できるようにする。Markdownベースのテンプレートにより、開発者はHTML/CSSの詳細を意識せずに、テキストベースでメール内容を定義できる。level（info/success/error）によるボタン色の自動調整など、UX向上の工夫も含まれている。

**画面へのアクセス方法**：このテンプレートは直接アクセスする画面ではなく、通知クラス内の`toMail()`メソッドで`MailMessage`オブジェクトを返却することで使用される。`MailChannel`がこのテンプレートをレンダリングしてメール送信を行う。

**主要な操作・処理内容**：
1. 挨拶文（Greeting）の表示：カスタム挨拶または「Hello!」/「Whoops!」（エラー時）
2. 導入文（Intro Lines）の表示：本文の導入部分
3. アクションボタンの表示：URL付きのコールトゥアクションボタン（オプション）
4. 結び文（Outro Lines）の表示：本文の結び部分
5. 署名（Salutation）の表示：カスタム署名または「Regards, {アプリ名}」
6. サブコピー（Subcopy）の表示：ボタンURLのテキストリンク（ボタンが使えない場合用）

**画面遷移**：メールテンプレートのため画面遷移は存在しない。ただし、アクションボタンをクリックすることで、指定されたURLへの遷移が可能。

**権限による表示制御**：特に権限による表示制御は行われない。通知の送信先は、Notifiableトレイトを使用するモデル（通常はUser）のメールアドレスによって決定される。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 30 | 通知管理 | 主機能 | 通知システムのメール送信処理 |
| 28 | メール管理 | 補助機能 | メール送信インフラストラクチャ連携 |
| 29 | Markdownレンダラー | 補助機能 | Markdown形式通知メールのレンダリング |

## 画面種別

メールテンプレート

## URL/ルーティング

このテンプレートは直接URLを持たない。通知システムを通じてメール送信時に使用される。

## 入出力項目

| 項目名 | 型 | 必須 | 説明 |
|--------|-----|------|------|
| $greeting | string\|null | 任意 | カスタム挨拶文 |
| $level | string | 必須 | 通知レベル（info/success/error） |
| $introLines | array | 必須 | 導入文の配列 |
| $actionText | string\|null | 任意 | アクションボタンのテキスト |
| $actionUrl | string\|null | 任意 | アクションボタンのURL |
| $outroLines | array | 必須 | 結び文の配列 |
| $salutation | string\|null | 任意 | カスタム署名 |
| $displayableActionUrl | string\|null | 任意 | 表示用URL（mailto:やtel:を除去） |

## 表示項目

| 項目名 | 説明 |
|--------|------|
| 挨拶文（Greeting） | メール冒頭の挨拶。カスタム値または「Hello!」/「Whoops!」 |
| 導入文（Intro Lines） | 本文の導入部分。複数行対応 |
| アクションボタン | URLリンク付きボタン。levelに応じて色が変化 |
| 結び文（Outro Lines） | 本文の結び部分。複数行対応 |
| 署名（Salutation） | メール末尾の署名。カスタム値または「Regards, {アプリ名}」 |
| サブコピー | ボタンのURLをテキストリンクとして表示（アクセシビリティ対応） |

## イベント仕様

### 1-メール送信処理

`MailChannel::send()`メソッドにより通知がメール送信される。

**処理フロー**:
1. `$notification->toMail($notifiable)` でMailMessageオブジェクトを取得
2. Markdownテンプレート（notifications::email）をレンダリング
3. メールメッセージを構築（宛先、件名、添付ファイル等）
4. メーラーを使用してメール送信

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

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

このコンポーネントは直接データベース操作を行わない。

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

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 |
|-------------|------|---------------|
| MSG-001 | 挨拶（通常） | Hello! |
| MSG-002 | 挨拶（エラー） | Whoops! |
| MSG-003 | 署名 | Regards, {config('app.name')} |
| MSG-004 | サブコピー | If you're having trouble clicking the "{actionText}" button, copy and paste the URL below into your web browser: |

## 例外処理

| 例外タイプ | 発生条件 | 対応処理 |
|-----------|---------|---------|
| - | - | このテンプレート自体は例外をスローしない |

## 備考

- `x-mail::message`コンポーネント内で構造化されたメールを生成
- `x-mail::button`コンポーネントでアクションボタンを描画
- levelに応じてボタンの色が変化（success: 緑、error: 赤、それ以外: primary）
- `@lang`ディレクティブで多言語対応
- `x-slot:subcopy`でサブコピーを定義（ボタンが使えない環境用のURLテキスト）
- 改行やフォーマットはMarkdownレンダラーが処理
- デフォルトのMarkdownテンプレートは`notifications::email`（`MailMessage::$markdown`プロパティ）

---

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

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

### 推奨読解順序

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

通知メールで使用されるデータ構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | SimpleMessage.php | `src/Illuminate/Notifications/Messages/SimpleMessage.php` | 基本的なメッセージプロパティ（level, greeting, introLines等） |
| 1-2 | MailMessage.php | `src/Illuminate/Notifications/Messages/MailMessage.php` | SimpleMessageを拡張したメール用メッセージクラス |

**読解のコツ**:
- `SimpleMessage`の`toArray()`メソッド（280-291行目）で、テンプレートに渡されるデータ構造を確認
- `MailMessage`の`$markdown`プロパティ（37行目）でデフォルトテンプレートが`notifications::email`であることを確認

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

メール送信処理の流れを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | MailChannel.php | `src/Illuminate/Notifications/Channels/MailChannel.php` | 通知のメール送信チャンネル |

**主要処理フロー**:
1. **55行目**: `$notification->toMail($notifiable)` でMailMessageを取得
2. **66-70行目**: メーラーを使用してメール送信
3. **94-104行目**: `buildView()` でMarkdownテンプレートをビルド
4. **112-117行目**: `buildMarkdownHtml()` でHTMLメールをレンダリング

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

Bladeテンプレートの構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | email.blade.php | `src/Illuminate/Notifications/resources/views/email.blade.php` | 通知メールのメインテンプレート |

**主要処理フロー**:
- **1行目**: `<x-mail::message>` でメールメッセージコンポーネントを使用
- **3-11行目**: 挨拶文の条件分岐（カスタム/Hello!/Whoops!）
- **14-17行目**: 導入文のループ出力
- **20-29行目**: アクションボタンの条件付き出力（levelに応じた色設定）
- **33-36行目**: 結び文のループ出力
- **39-44行目**: 署名の条件分岐
- **47-56行目**: サブコピーの条件付き出力（ボタンURL表示）

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

```
Notification::send($notifiable, new CustomNotification)
    │
    └─ MailChannel::send($notifiable, $notification)
           │
           ├─ $notification->toMail($notifiable)
           │      └─ MailMessage（データ構築）
           │
           ├─ buildView($message)
           │      └─ buildMarkdownHtml($message)
           │             └─ Markdown::render('notifications::email', $data)
           │
           └─ email.blade.php（テンプレートレンダリング）
                  │
                  ├─ x-mail::message（メールコンポーネント）
                  │      ├─ greeting（挨拶）
                  │      ├─ introLines（導入文）
                  │      ├─ x-mail::button（アクションボタン）
                  │      ├─ outroLines（結び文）
                  │      ├─ salutation（署名）
                  │      └─ x-slot:subcopy（サブコピー）
                  │
                  └─ HTMLメール生成
```

### データフロー図

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

Notification ───▶ toMail() ───▶ MailMessage ───▶ email.blade.php ───▶ HTMLメール
   │                                 │                    │
   │              (MailChannel)      │                    │
   └─ $notifiable                   └─ level            └─ x-mail::message
      (送信先)                         greeting             x-mail::button
                                       introLines
                                       actionText/Url
                                       outroLines
                                       salutation
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| email.blade.php | `src/Illuminate/Notifications/resources/views/email.blade.php` | テンプレート | 通知メールのメインテンプレート |
| MailMessage.php | `src/Illuminate/Notifications/Messages/MailMessage.php` | ソース | メール用メッセージクラス |
| SimpleMessage.php | `src/Illuminate/Notifications/Messages/SimpleMessage.php` | ソース | メッセージの基本クラス |
| MailChannel.php | `src/Illuminate/Notifications/Channels/MailChannel.php` | ソース | メール送信チャンネル |
| message.blade.php | `src/Illuminate/Mail/resources/views/html/message.blade.php` | テンプレート | HTMLメールのメッセージコンポーネント |
| button.blade.php | `src/Illuminate/Mail/resources/views/html/button.blade.php` | テンプレート | HTMLメールのボタンコンポーネント |
