# 帳票設計書 6-Mail Attachment

## 概要

本ドキュメントは、Laravel FrameworkにおけるMail Attachment（メール添付ファイル）機能の設計仕様を定義する。メールに添付するファイル（帳票）を管理する機能であり、Mailable::attach()で利用可能。

### 本帳票の処理概要

Mail Attachment機能は、Laravelのメール送信機能（Mailable）において、ファイルを添付する仕組みを提供する。ローカルファイル、ストレージ上のファイル、インメモリデータ、アップロードされたファイルなど、様々なソースからの添付に対応している。

**業務上の目的・背景**：業務システムでは、請求書PDF、月次レポート、データエクスポートファイルなどをメールに添付して送信する必要がある。Laravel Mail Attachment機能は、Fluent APIを使用して直感的に添付ファイルを設定でき、ストレージ抽象化レイヤーとの統合により、ローカル・クラウドストレージを問わず一貫した方法でファイルを添付できる。

**帳票の利用シーン**：
- 請求書PDFのメール送付
- 月次レポートの定期配信
- データエクスポート結果の送信
- システム通知への添付ファイル

**主要な出力内容**：
1. ファイルパスからの添付（attach()）
2. インメモリデータの添付（attachData()）
3. ストレージからの添付（attachFromStorage()、attachFromStorageDisk()）
4. カスタムファイル名・MIMEタイプの設定

**帳票の出力タイミング**：Mailableオブジェクトの構築時にattach()等のメソッドで添付ファイルを設定し、send()またはqueue()でメール送信時に実際の添付処理が行われる。

**帳票の利用者**：アプリケーション開発者、メール受信者（添付ファイル取得者）

## 帳票種別

メール添付ファイル / ファイル添付

## 利用画面

| 画面No | 画面名 | URL/ルーティング | 出力操作 |
|--------|--------|-----------------|---------|
| - | メール送信処理 | - | Mailable::attach()呼び出し |

## 出力形式

### 基本仕様

| 項目 | 内容 |
|-----|------|
| ファイル形式 | 任意（PDF / Excel / 画像等） |
| 用紙サイズ | - |
| 向き | - |
| ファイル名 | asオプションまたはAttachment::as()で指定 |
| 出力方法 | メール添付（MIME エンコード） |
| 文字コード | ファイル依存 |

### 添付方法一覧

| メソッド | 説明 | ソース |
|---------|------|--------|
| attach() | ファイルパスから添付 | ローカルファイル |
| attachData() | インメモリデータを添付 | バイナリデータ |
| attachFromStorage() | デフォルトストレージから添付 | Storageディスク |
| attachFromStorageDisk() | 指定ストレージから添付 | 任意のディスク |
| attachMany() | 複数ファイルを一括添付 | 複数ソース |

## 帳票レイアウト

### レイアウト概要

Mail Attachmentはメールの添付ファイルとして送信されるため、ファイル自体のレイアウトは元ファイルに依存する。

```
┌─────────────────────────────────────┐
│          メールヘッダー              │
├─────────────────────────────────────┤
│          メール本文                 │
├─────────────────────────────────────┤
│          添付ファイル部              │
│   ├─ ファイル1                      │
│   ├─ ファイル2                      │
│   └─ ...                           │
└─────────────────────────────────────┘
```

### 添付ファイル属性

| No | 項目名 | 説明 | データ取得元 | 表示形式 |
|----|-------|------|-------------|---------|
| 1 | ファイル名 | 添付ファイル名 | as オプション | filename.pdf |
| 2 | MIMEタイプ | ファイルの種類 | mime オプション | application/pdf |
| 3 | ファイルデータ | 添付ファイル本体 | ファイルパス/データ | バイナリ |

## 出力条件

### 抽出条件

| 条件名 | 説明 | 必須 |
|-------|------|-----|
| file/data/path | 添付するファイル/データ/パス | Yes |
| as | 表示ファイル名 | No |
| mime | MIMEタイプ | No（自動検出） |
| disk | ストレージディスク名 | No（attachFromStorageDisk時） |

### ソート順

添付ファイルはattach()呼び出し順に追加される。

| 優先度 | 項目 | 昇順/降順 |
|-------|------|---------|
| - | - | - |

### 改ページ条件

メール添付のため、改ページ条件は適用されない。

## データベース参照仕様

### 参照テーブル一覧

Mail Attachment自体はデータベースを参照しない。添付ファイルのパス取得にデータベースを参照する場合は、呼び出し元で処理する。

| テーブル名 | 用途 | 結合条件 |
|-----------|------|---------|
| - | - | - |

## 計算仕様

### 計算項目一覧

| 項目名 | 計算式 | 端数処理 | 備考 |
|-------|-------|---------|------|
| - | - | - | 添付処理はSymfonyメーラーに委譲 |

## 処理フロー

### 出力フロー

```mermaid
flowchart TD
    A[attach*メソッド呼び出し] --> B{添付タイプ判定}
    B -->|Attachableインターフェース| C[toMailAttachment()呼び出し]
    B -->|Attachmentオブジェクト| D[attachTo()呼び出し]
    B -->|ファイルパス| E[attachments配列に追加]
    C --> D
    D --> E
    E --> F[send/queue呼び出し]
    F --> G[buildAttachments実行]
    G --> H[各添付を処理]
    H --> I{添付種別}
    I -->|attachments| J[Message::attach]
    I -->|rawAttachments| K[Message::attachData]
    I -->|diskAttachments| L[buildDiskAttachments]
    J --> M[メール送信]
    K --> M
    L --> M
```

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 表示メッセージ | 対処方法 |
|----------|---------|--------------|---------|
| ファイル不存在 | 添付ファイルが存在しない | RuntimeException | ファイルパスを確認 |
| ファイル名未指定 | attachData時にnameがnull | Attachment requires a filename | as()でファイル名指定 |
| ストレージエラー | ディスクからの読み取り失敗 | UnableToReadFile | ストレージ設定確認 |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定添付ファイル数 | 複数（メールサイズ制限に依存） |
| 目標処理時間 | ファイルサイズに依存 |
| 添付サイズ上限 | メールサーバー設定に依存 |

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

- 機密ファイルの添付時は、受信者の認証を確認すること
- ユーザー入力をファイル名に使用する場合は、サニタイズが必要
- 添付ファイルサイズの制限を設けること
- ウイルススキャンを検討すること

## 備考

- Attachableインターフェースを実装することで、カスタムオブジェクトを添付可能
- Attachmentクラスはファクトリメソッドパターンを使用
- diskAttachmentsはメール送信時にストレージから読み込まれる

---

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

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

### 推奨読解順序

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

Mailableクラスの添付ファイル関連プロパティとAttachmentクラスの構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Mailable.php | `src/Illuminate/Mail/Mailable.php` | $attachments, $rawAttachments, $diskAttachmentsプロパティ |
| 1-2 | Attachment.php | `src/Illuminate/Mail/Attachment.php` | Attachmentクラスの構造 |

**読解のコツ**: 3種類の添付方法（ファイルパス、インメモリデータ、ストレージ）それぞれの格納先を理解する。

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

添付メソッドの実装を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Mailable.php | `src/Illuminate/Mail/Mailable.php` | attach()メソッドの実装 |

**主要処理フロー**:
1. **行963-985**: attach()メソッドの実装
2. **行971-972**: Attachableインターフェースの処理
3. **行975-977**: Attachmentオブジェクトの処理
4. **行979-982**: ファイルパスの配列への追加
5. **行1074-1100**: attachFromStorageDisk()メソッドの実装
6. **行1134-1150**: attachData()メソッドの実装

#### Step 3: ビルド処理を理解する

メール送信時の添付ファイルビルド処理を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Mailable.php | `src/Illuminate/Mail/Mailable.php` | buildAttachments()メソッド |
| 3-2 | Mailable.php | `src/Illuminate/Mail/Mailable.php` | buildDiskAttachments()メソッド |

**主要処理フロー**:
- **行483-502**: buildAttachments()メソッド - 各種添付の処理
- **行504-523**: buildDiskAttachments()メソッド - ストレージからの添付処理

#### Step 4: Attachmentクラスを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Attachment.php | `src/Illuminate/Mail/Attachment.php` | ファクトリメソッド群 |

**主要処理フロー**:
- **行49-57**: fromPath()メソッド - パスからAttachment生成
- **行72-82**: fromData()メソッド - データからAttachment生成
- **行102-110**: fromStorage()メソッド - ストレージからAttachment生成
- **行115-132**: fromStorageDisk()メソッド - 指定ディスクからAttachment生成
- **行185-210**: attachTo()メソッド - Mailableへの添付処理

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

```
Mailable::attach($file, $options)
    │
    ├─ [Attachable] $file->toMailAttachment()
    │
    ├─ [Attachment] $file->attachTo($this, $options)
    │       │
    │       └─ attachWith($pathStrategy, $dataStrategy)
    │              ├─ $mail->attach($path, $options)
    │              └─ $mail->attachData($data, $options)
    │
    └─ [string] $this->attachments[] = compact('file', 'options')

Mailable::send()
    │
    └─ buildAttachments($message)
           │
           ├─ foreach $this->attachments
           │      └─ $message->attach($file, $options)
           │
           ├─ foreach $this->rawAttachments
           │      └─ $message->attachData($data, $name, $options)
           │
           └─ buildDiskAttachments($message)
                  └─ foreach $this->diskAttachments
                         └─ $message->attachData($storage->get($path), ...)
```

### データフロー図

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

ファイルパス    ───▶ Mailable::attach()  ───▶ $attachments配列
                          │
インメモリデータ ───▶ Mailable::attachData() ─▶ $rawAttachments配列
                          │
ストレージパス  ───▶ Mailable::attachFromStorage() ─▶ $diskAttachments配列
                          │
                          ▼
                    Mailable::send()
                          │
                          ▼
                    buildAttachments()
                          │
                          ▼
                    Message::attach/attachData
                          │
                          ▼
                    メール送信（添付ファイル付き）
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Mailable.php | `src/Illuminate/Mail/Mailable.php` | ソース | attach()等のメソッド実装 |
| Attachment.php | `src/Illuminate/Mail/Attachment.php` | ソース | Attachmentクラス |
| Attachable.php | `src/Illuminate/Contracts/Mail/Attachable.php` | ソース | Attachableインターフェース |
| Message.php | `src/Illuminate/Mail/Message.php` | ソース | 実際の添付処理 |
| Mail.php | `src/Illuminate/Support/Facades/Mail.php` | ソース | Facadeクラス |
