# 通知設計書 1-BaseMailer#welcome

## 概要

本ドキュメントは、Rails ActionMailerフレームワークにおけるBaseMailer#welcomeメソッドによるウェルカムメール通知の設計を記述する。

### 本通知の処理概要

BaseMailer#welcomeは、新規ユーザー向けの初回ウェルカムメールを送信するためのテスト用メーラーメソッドである。このメソッドは、ActionMailerの基本的なメール送信機能を実証するために設計されている。

**業務上の目的・背景**：新規ユーザーがシステムに登録した際に、歓迎の意を伝え、サービス利用開始を促すことを目的とする。ウェルカムメールは、ユーザーエンゲージメントの第一歩であり、ユーザーとの関係構築において重要な役割を果たす。本実装はテスト用であり、ActionMailerの基本機能（ヘッダー設定、テンプレート利用、配信処理）の動作確認を主目的とする。

**通知の送信タイミング**：メーラーメソッドが呼び出された時点で送信される。通常は、ユーザー登録処理完了後にコントローラーやサービスクラスから`BaseMailer.welcome.deliver_now`または`BaseMailer.welcome.deliver_later`として呼び出される。

**通知の受信者**：デフォルトでは`system@test.lindsaar.net`宛に送信される。ただし、メソッド呼び出し時にハッシュパラメータで`to:`オプションを指定することで、任意の宛先に変更可能。

**通知内容の概要**：件名「The first email on new API!」とともに、welcomeテンプレート（welcome.erb）の内容「Welcome」が本文として送信される。カスタムヘッダー「X-SPAM: Not SPAM」が付与される。

**期待されるアクション**：受信者はメールを確認し、サービスの利用を開始することが期待される。テスト用途では、メール配信機能が正常に動作していることを確認する。

## 通知種別

メール

## 送信仕様

### 基本情報

| 項目 | 内容 |
|-----|------|
| 送信方式 | 同期（deliver_now）/ 非同期（deliver_later） |
| 優先度 | 中（デフォルト） |
| リトライ | 配信メソッドに依存（SMTPの場合は設定による） |

### 送信先決定ロジック

デフォルト設定として`system@test.lindsaar.net`が指定されている。メソッド呼び出し時に`to:`パラメータを渡すことで上書き可能。

```ruby
# デフォルト宛先を使用
BaseMailer.welcome

# 宛先を指定
BaseMailer.welcome(to: "user@example.com")
```

## 通知テンプレート

### メール通知の場合

| 項目 | 内容 |
|-----|------|
| 送信元アドレス | jose@test.plataformatec.com |
| 送信元名称 | （未設定） |
| 件名 | The first email on new API! |
| 形式 | text/plain |

### 本文テンプレート

```
Welcome
```

テンプレートファイル: `actionmailer/test/fixtures/base_mailer/welcome.erb`

### 添付ファイル

本メソッドでは添付ファイルは使用されない。

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| （なし） | 本テンプレートではインスタンス変数を使用しない | - | - |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| API呼び出し | `BaseMailer.welcome` メソッド実行 | なし（常に送信） | メーラーメソッドの直接呼び出し |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| perform_deliveries = false | ActionMailerの設定で配信を無効化している場合 |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[BaseMailer.welcome 呼び出し] --> B[MessageDelivery オブジェクト生成]
    B --> C{deliver_now or deliver_later?}
    C -->|deliver_now| D[メーラーインスタンス生成]
    C -->|deliver_later| E[ActiveJob キューイング]
    D --> F[welcomeメソッド実行]
    E --> G[ジョブ実行時にメーラー処理]
    F --> H[mail メソッド呼び出し]
    G --> H
    H --> I[ヘッダー設定 X-SPAM]
    I --> J[テンプレート welcome.erb レンダリング]
    J --> K[Mail::Message 生成]
    K --> L[deliver.action_mailer 計装イベント発火]
    L --> M[SMTP/配信メソッドで送信]
    M --> N[終了]
```

## データベース参照・更新仕様

### 参照テーブル一覧

本メソッドはデータベースを参照しない（テスト用メーラー）。

### 更新テーブル一覧

本メソッドはデータベースを更新しない。

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| テンプレート未検出 | welcome.erbが存在しない場合 | ActionView::MissingTemplate例外 |
| SMTP接続エラー | SMTPサーバーに接続できない場合 | raise_delivery_errorsがtrueの場合例外発生 |
| 宛先不正 | メールアドレス形式が不正 | Mail gem側でバリデーションエラー |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | ActiveJob設定に依存（deliver_later使用時） |
| リトライ間隔 | ActiveJob設定に依存 |
| リトライ対象エラー | デフォルトでは全てのStandardError |

## 配信設定

### レート制限

| 項目 | 内容 |
|-----|------|
| 1分あたり上限 | 設定なし（SMTPサーバー側の制限に依存） |
| 1日あたり上限 | 設定なし |

### 配信時間帯

制限なし

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

- テスト用メーラーのため、本番環境での使用は非推奨
- 送信元・送信先アドレスがハードコードされている
- X-SPAMヘッダーはスパムフィルター回避目的ではなく、カスタムヘッダー設定のデモンストレーション

## 備考

- 本メーラーはActionMailerのテストスイートで使用されるテスト用実装
- I18n対応: 件名は`base_mailer.welcome.subject`キーで国際化可能
- デフォルトのReply-To: `Mikel <mikel@test.lindsaar.net>`

---

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

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

### 推奨読解順序

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

まず、ActionMailerが生成するMail::Messageオブジェクトの構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | base.rb | `actionmailer/lib/action_mailer/base.rb` | L503-508: デフォルトパラメータ（mime_version, charset, content_type, parts_order）の定義 |
| 1-2 | message_delivery.rb | `actionmailer/lib/action_mailer/message_delivery.rb` | L51-62: MessageDeliveryクラスの初期化、遅延評価の仕組み |

**読解のコツ**: ActionMailerはMail gemをラップしており、最終的にMail::Messageオブジェクトが生成される。@_messageインスタンス変数がMail::Messageを保持する。

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

処理の起点となるメーラークラスとメソッドを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | base_mailer.rb | `actionmailer/test/mailers/base_mailer.rb` | L3-8: BaseMailerクラス定義、デフォルト設定（to, from, reply_to） |
| 2-2 | base_mailer.rb | `actionmailer/test/mailers/base_mailer.rb` | L10-13: welcomeメソッドの実装 |

**主要処理フロー**:
1. **L11**: `headers["X-SPAM"] = "Not SPAM"` - カスタムヘッダーの設定
2. **L12**: `mail({ subject: "The first email on new API!" }.merge!(hash))` - mailメソッド呼び出しでMail::Message生成

#### Step 3: ActionMailer::Base の mail メソッドを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | base.rb | `actionmailer/lib/action_mailer/base.rb` | L865-898: mailメソッドの実装 |
| 3-2 | base.rb | `actionmailer/lib/action_mailer/base.rb` | L942-949: apply_defaultsメソッド - デフォルト値の適用 |
| 3-3 | base.rb | `actionmailer/lib/action_mailer/base.rb` | L992-1003: collect_responses_from_templatesメソッド - テンプレートの収集とレンダリング |

**主要処理フロー**:
- **L871**: `headers = apply_defaults(headers)` - デフォルト設定をマージ
- **L882**: `responses = collect_responses(headers, &block)` - テンプレートをレンダリング
- **L885**: `create_parts_from_responses(message, responses)` - メールパートを生成

#### Step 4: 配信処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | message_delivery.rb | `actionmailer/lib/action_mailer/message_delivery.rb` | L157-163: deliver_nowメソッド |
| 4-2 | message_delivery.rb | `actionmailer/lib/action_mailer/message_delivery.rb` | L136-138: deliver_laterメソッド |
| 4-3 | base.rb | `actionmailer/lib/action_mailer/base.rb` | L593-598: deliver_mailメソッド - 計装イベントの発火 |

**主要処理フロー**:
- **L159-161**: コールバック実行とmessage.deliver呼び出し
- **L594**: `ActiveSupport::Notifications.instrument("deliver.action_mailer")` - 計装イベント

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

```
BaseMailer.welcome (クラスメソッド呼び出し)
    │
    ├─ ActionMailer::Base.method_missing (L624-629)
    │      └─ MessageDelivery.new(self, :welcome, *args)
    │
    └─ MessageDelivery#deliver_now (L157-163)
           │
           ├─ processed_mailer (L168-172)
           │      └─ BaseMailer.new.process(:welcome, *args)
           │             │
           │             └─ BaseMailer#welcome (L10-13)
           │                    ├─ headers["X-SPAM"] = "Not SPAM"
           │                    └─ mail(subject: "...")
           │                           │
           │                           ├─ apply_defaults
           │                           ├─ collect_responses_from_templates
           │                           └─ create_parts_from_responses
           │
           └─ run_callbacks(:deliver)
                  └─ message.deliver
                         └─ ActionMailer::Base.deliver_mail
                                └─ ActiveSupport::Notifications.instrument
```

### データフロー図

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

呼び出しパラメータ      ───▶ MessageDelivery              ───▶ Mail::Message
  - to (optional)              │
  - subject (optional)         ▼
  - その他ヘッダー       ───▶ BaseMailer#welcome
                               │
                               ├─ headers["X-SPAM"]設定
                               ▼
                         ───▶ mail() メソッド
                               │
                               ├─ apply_defaults
                               │    (from, to, reply_to適用)
                               │
                               ├─ collect_responses_from_templates
                               │    (welcome.erb レンダリング)
                               │
                               └─ create_parts_from_responses
                                    (Mail::Messageにbody設定)

welcome.erb テンプレート ───▶ レンダリング結果           ───▶ メール本文 "Welcome"
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| base_mailer.rb | `actionmailer/test/mailers/base_mailer.rb` | ソース | テスト用メーラークラス定義 |
| base.rb | `actionmailer/lib/action_mailer/base.rb` | ソース | ActionMailer基底クラス |
| message_delivery.rb | `actionmailer/lib/action_mailer/message_delivery.rb` | ソース | メール配信ラッパー |
| callbacks.rb | `actionmailer/lib/action_mailer/callbacks.rb` | ソース | 配信コールバック機能 |
| welcome.erb | `actionmailer/test/fixtures/base_mailer/welcome.erb` | テンプレート | メール本文テンプレート |
| base_test.rb | `actionmailer/test/base_test.rb` | テスト | 機能テスト |
