# 機能設計書 28-メール管理

## 概要

本ドキュメントは、Laravel Frameworkのメール管理機能（MailManager）の設計仕様を記載する。MailManagerは複数のメール送信ドライバを管理し、メールの作成・送信機能を提供するコンポーネントである。

### 本機能の処理概要

MailManagerは、SMTP、Mailgun、Postmark、Amazon SES、Resend、Sendmailなど複数のメール送信バックエンドを統一的なインターフェースで管理し、メール送信機能を提供する。

**業務上の目的・背景**：Webアプリケーションでは、ユーザー登録確認、パスワードリセット、注文確認、通知メールなど、様々な場面でメール送信が必要となる。MailManagerは、これらのメール送信を統一的なAPIで提供し、送信ドライバの切り替えや複数ドライバのフェイルオーバーをサポートする。

**機能の利用シーン**：ユーザー登録時のウェルカムメール、パスワードリセットメール、注文確認メール、出荷通知メール、ニュースレター配信、システムアラートメールなど。

**主要な処理内容**：
1. mailer()メソッドでMailerインスタンスを取得
2. createSymfonyTransport()でトランスポートを生成
3. Mailableクラスを使用したメール内容の定義
4. send()メソッドでメール送信
5. キュー経由での非同期送信

**関連システム・外部連携**：Symfony Mailerコンポーネント、各メールサービスAPI（Mailgun、Postmark、SES、Resend）、SMTPサーバー、Queueシステムとの連携。

**権限による制御**：本機能自体には権限制御はない。メール送信はアプリケーションロジックで制御。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | - | 内部機能 | メール送信処理 |

## 機能種別

メール送信 / 外部サービス連携

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| name | string | No | メーラー名（設定名） | 有効な設定名 |
| mailable | Mailable | Yes | メール内容を定義したクラス | Mailableインスタンス |

### 入力データソース

- 設定ファイル（config/mail.php）
- Mailableクラスの定義

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| mailer | Mailer | メーラーインスタンス |
| sentMessage | SentMessage | 送信済みメッセージ |

### 出力先

- 外部メールサーバー（SMTP、API）
- ログファイル（logドライバ使用時）
- メモリ（arrayドライバ使用時）

## 処理フロー

### 処理シーケンス

```
1. MailManager::mailer()でメーラーを取得
   └─ getDefaultDriver()でデフォルトドライバ取得
   └─ resolve()で設定を解決
   └─ build()でMailerインスタンス生成

2. Mailer::send()でメール送信
   └─ Mailableのbuild()を実行
   └─ renderView()でビューをレンダリング
   └─ SymfonyTransportで送信

3. 送信完了
   └─ MessageSentイベント発火
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[MailManager::mailer]
    B --> C[getDefaultDriver]
    C --> D[getConfig]
    D --> E[build]
    E --> F[createSymfonyTransport]
    F --> G{transport種別}
    G -->|smtp| H[EsmtpTransport]
    G -->|mailgun| I[MailgunTransport]
    G -->|postmark| J[PostmarkTransport]
    G -->|ses/ses-v2| K[SesTransport]
    G -->|resend| L[ResendTransport]
    G -->|sendmail| M[SendmailTransport]
    G -->|log| N[LogTransport]
    G -->|array| O[ArrayTransport]
    G -->|failover| P[FailoverTransport]
    H --> Q[new Mailer]
    I --> Q
    J --> Q
    K --> Q
    L --> Q
    M --> Q
    N --> Q
    O --> Q
    P --> Q
    Q --> R[setGlobalAddress]
    R --> S[Mailer::send]
    S --> T[Mailable::build]
    T --> U[renderView]
    U --> V[Transport::send]
    V --> W[MessageSent event]
    W --> X[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | グローバルFrom | 全メールに適用されるFromアドレスを設定可能 | from設定時 |
| BR-02 | グローバルReplyTo | 全メールに適用されるReplyToを設定可能 | reply_to設定時 |
| BR-03 | フェイルオーバー | 最初のトランスポートが失敗した場合、次のトランスポートを試行 | failoverドライバ使用時 |
| BR-04 | ラウンドロビン | 複数トランスポートを順番に使用 | roundrobinドライバ使用時 |

### 計算ロジック

- SMTPポート465はsmtps、それ以外はsmtpスキーム
- フェイルオーバー再試行: retry_after秒後（デフォルト60秒）

## データベース操作仕様

本機能はデータベースを直接操作しない。キュー経由の場合、キューテーブルにジョブが保存される。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| InvalidArgumentException | 設定エラー | 未定義のメーラー名 | 設定ファイルを確認 |
| InvalidArgumentException | トランスポートエラー | 未サポートのトランスポート | サポートされるドライバを使用 |
| TransportException | 送信エラー | SMTP接続失敗、API認証失敗 | 設定・認証情報を確認 |

### リトライ仕様

failoverドライバ使用時、retry_after秒後に次のトランスポートに切り替え。

## トランザクション仕様

本機能はトランザクションを使用しない。

## パフォーマンス要件

- SMTPタイムアウト: configで設定可能
- 大量メール送信: キュー経由で非同期処理を推奨
- APIベースのトランスポート（Mailgun等）はSMTPより高速

## セキュリティ考慮事項

- **認証情報管理**: APIキー、SMTP認証情報は環境変数で管理
- **TLS/SSL**: SMTP通信は暗号化を推奨
- **メールヘッダインジェクション**: Symfonyコンポーネントで対策済み
- **スパム対策**: 送信レート制限はメールサービス側で設定

## 備考

- MailServiceProviderで自動登録
- 'mail.manager'エイリアスでコンテナから解決可能
- Mail Facadeで簡易アクセス可能
- Mailableクラスでメール内容を定義

---

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

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

### 推奨読解順序

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

まず、契約インターフェースを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Factory.php | `src/Illuminate/Contracts/Mail/Factory.php` | メールファクトリの契約 |
| 1-2 | Mailer.php | `src/Illuminate/Contracts/Mail/Mailer.php` | メーラーの契約 |

**読解のコツ**: send()、raw()メソッドのシグネチャを確認。

#### Step 2: マネージャクラスを理解する

MailManagerでのドライバ管理を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | MailManager.php | `src/Illuminate/Mail/MailManager.php` | ドライバ管理とトランスポート生成 |

**主要処理フロー**:
- **63-66行目**: コンストラクタでアプリケーションインスタンスを受け取る
- **74-79行目**: mailer()でメーラーを取得
- **98-132行目**: resolve()でメーラーを解決
- **140-154行目**: build()でMailerインスタンスを生成
- **164-181行目**: createSymfonyTransport()でトランスポートを生成
- **189-209行目**: createSmtpTransport()でSMTPトランスポート生成
- **254-268行目**: createSesTransport()でSESトランスポート生成
- **340-354行目**: createMailgunTransport()でMailgunトランスポート生成
- **389-403行目**: createFailoverTransport()でフェイルオーバー設定

#### Step 3: Mailerクラスを理解する

実際のメール送信処理を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Mailer.php | `src/Illuminate/Mail/Mailer.php` | メール送信処理 |
| 3-2 | PendingMail.php | `src/Illuminate/Mail/PendingMail.php` | Fluent APIでのメール構築 |

#### Step 4: Mailableを理解する

メール内容の定義を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Mailable.php | `src/Illuminate/Mail/Mailable.php` | メール内容の基底クラス |

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

```
MailServiceProvider::register()
    │
    └─ MailManager (singleton)

MailManager::mailer()
    │
    ├─ getDefaultDriver()
    │      └─ config('mail.default')
    │
    ├─ get() ─── キャッシュ確認
    │
    └─ resolve()
           │
           ├─ getConfig()
           │
           └─ build()
                  │
                  ├─ createSymfonyTransport()
                  │      │
                  │      └─ create{Transport}Transport()
                  │
                  └─ new Mailer(transport)

Mail::to($user)->send($mailable)
    │
    └─ PendingMail::send()
           │
           └─ Mailer::send()
                  │
                  ├─ Mailable::build()
                  │
                  └─ SymfonyTransport::send()
```

### データフロー図

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

Mailableクラス
    │
    ├─ to/cc/bcc
    ├─ subject
    ├─ view/markdown
    └─ attachments
           │
           ▼
    MailManager::mailer()
           │
           ▼
    Mailer::send()
           │
           ├─ renderView()
           │      └─ Blade/Markdown
           │
           └─ SymfonyEmail
                  │
                  ▼
    Transport::send()
           │
           ├─ SMTP ───────▶ メールサーバー
           ├─ Mailgun API ─▶ Mailgun
           ├─ SES API ─────▶ Amazon SES
           └─ Log ─────────▶ ログファイル
                                │
                                ▼
                         SentMessage
                                │
                                ▼
                         MessageSent Event
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| MailManager.php | `src/Illuminate/Mail/MailManager.php` | ソース | メーラー管理 |
| Mailer.php | `src/Illuminate/Mail/Mailer.php` | ソース | メール送信処理 |
| Mailable.php | `src/Illuminate/Mail/Mailable.php` | ソース | メール定義基底クラス |
| PendingMail.php | `src/Illuminate/Mail/PendingMail.php` | ソース | Fluent API |
| MailServiceProvider.php | `src/Illuminate/Mail/MailServiceProvider.php` | ソース | サービス登録 |
| SesTransport.php | `src/Illuminate/Mail/Transport/SesTransport.php` | ソース | SESトランスポート |
| SesV2Transport.php | `src/Illuminate/Mail/Transport/SesV2Transport.php` | ソース | SES v2トランスポート |
| ResendTransport.php | `src/Illuminate/Mail/Transport/ResendTransport.php` | ソース | Resendトランスポート |
| LogTransport.php | `src/Illuminate/Mail/Transport/LogTransport.php` | ソース | ログトランスポート |
| ArrayTransport.php | `src/Illuminate/Mail/Transport/ArrayTransport.php` | ソース | テスト用トランスポート |
| Markdown.php | `src/Illuminate/Mail/Markdown.php` | ソース | Markdownメール |
| Factory.php | `src/Illuminate/Contracts/Mail/Factory.php` | インターフェース | 契約定義 |
| Mailer.php | `src/Illuminate/Contracts/Mail/Mailer.php` | インターフェース | 契約定義 |
