# 画面設計書 58-メール設定

## 概要

本ドキュメントは、Shopware 6 管理画面におけるメール設定（sw-settings-mailer）画面の設計書です。ECサイトからのメール送信に使用するメールサーバーの設定を行う画面について記述します。

### 本画面の処理概要

**業務上の目的・背景**：ECサイトでは注文確認、発送通知、パスワードリセットなど、様々なメールを顧客に送信する必要があります。本画面では、メール送信に使用するサーバー設定（SMTPサーバー、ローカルsendmail、環境変数設定）を構成し、メール配信の基盤を整備します。

**画面へのアクセス方法**：管理画面にログイン後、左メニューの「設定」 > 「システム」セクション > 「メール設定」をクリックしてアクセスします。

**主要な操作・処理内容**：
1. メールエージェントの選択（ローカル、SMTP、SMTP+OAuth、環境変数）
2. SMTPサーバー設定（ホスト、ポート、ユーザー名、パスワード、暗号化方式）
3. 送信者アドレスの設定
4. 配信先アドレスのオーバーライド（テスト用）
5. 配信無効化の設定（テスト環境用）
6. sendmailオプションの設定

**画面遷移**：設定メニュー → メール設定画面。単一画面で設定を完結します。

**権限による表示制御**：`system.system_config`権限で設定変更可能です。権限がない場合、画面にアクセスできません。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 59 | メールテンプレート | 関連 | メールテンプレートの送信設定 |

## 画面種別

設定

## URL/ルーティング

| 画面 | URL | コンポーネント |
|------|-----|---------------|
| メール設定 | `#/sw/settings/mailer/index` | sw-settings-mailer |

## 入出力項目

### メール設定画面

| 項目名 | 項目ID | 型 | 入力/出力 | 必須 | 説明 |
|--------|--------|-----|----------|------|------|
| メールエージェント | core.mailerSettings.emailAgent | string | 入力 | - | メール送信方式（local/smtp/smtp+oauth/空） |
| SMTPホスト | core.mailerSettings.host | string | 入力 | 条件付 | SMTPサーバーのホスト名（SMTP選択時必須） |
| SMTPポート | core.mailerSettings.port | number | 入力 | 条件付 | SMTPサーバーのポート番号（SMTP選択時必須） |
| SMTPユーザー名 | core.mailerSettings.username | string | 入力 | - | SMTP認証用ユーザー名 |
| SMTPパスワード | core.mailerSettings.password | string | 入力 | - | SMTP認証用パスワード |
| 暗号化 | core.mailerSettings.encryption | string | 入力 | - | 暗号化方式（ssl/tls/null） |
| 送信者アドレス | core.mailerSettings.senderAddress | string | 入力 | - | メール送信元アドレス |
| 配信先アドレス | core.mailerSettings.deliveryAddress | string | 入力 | - | 全メールの配信先オーバーライド |
| 配信無効化 | core.mailerSettings.disableDelivery | boolean | 入力 | - | メール配信を無効化（テスト用） |
| sendmailオプション | core.mailerSettings.sendMailOptions | string | 入力 | - | sendmailコマンドオプション |

## 表示項目

### メール設定画面

| 項目名 | 説明 |
|--------|------|
| メールエージェント選択 | ローカル/SMTP/SMTP+OAuth/環境変数からの選択 |
| SMTP設定カード | SMTPモード選択時に表示される詳細設定 |
| sendmail設定カード | ローカルモード選択時に表示される設定 |
| 送信者アドレス | 全メールの送信元アドレス設定 |
| テスト設定 | 配信先オーバーライドと配信無効化 |

## イベント仕様

### 1-保存ボタン押下

ユーザーが「保存」ボタンを押下すると、以下の処理が実行されます：
1. SMTPモードの場合、validateSmtpConfigurationでホストとポートのバリデーション
2. ローカルモードの場合、SMTP関連設定をリセット
3. systemConfigApiService.saveValuesでシステム設定を保存
4. 保存完了後、設定を再読み込み

### 2-メールエージェント変更

メールエージェントを変更すると、選択に応じた設定カードが表示/非表示になります：
- local: sendmailオプション設定のみ
- smtp/smtp+oauth: SMTP設定カード
- 空（環境変数）: 設定項目なし

### 3-初期設定検知

createdComponentで設定が読み込まれ、emailAgentが未設定の場合はisFirstConfigurationがtrueに設定されます。初期設定時は環境変数モードがデフォルトです。

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| 保存ボタン押下 | system_config | INSERT/UPDATE | メール設定の保存 |

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

#### system_config

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| INSERT/UPDATE | configuration_key | core.mailerSettings.* | メール設定のキー |
| INSERT/UPDATE | configuration_value | JSON形式 | 設定値 |
| INSERT/UPDATE | sales_channel_id | NULL | グローバル設定 |

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 | 表示条件 |
|------------|------|--------------|----------|
| sw-settings-mailer.card-smtp.error.notificationMessage | エラー | SMTP設定が無効です | SMTPバリデーションエラー時 |
| global.default.error | エラー | エラーが発生しました | 一般エラー時 |

## 例外処理

| 例外ケース | 処理内容 |
|-----------|---------|
| 権限不足 | 画面へのアクセスを拒否 |
| SMTPホスト未入力 | smtpHostErrorを設定し、保存を中止 |
| SMTPポート未入力/不正 | smtpPortErrorを設定し、保存を中止 |
| 通信エラー | エラー通知を表示し、ローディング状態を解除 |

## 備考

- メールエージェントのオプション：
  - `local`: ローカルのsendmailを使用
  - `smtp`: SMTPサーバーを使用
  - `smtp+oauth`: OAuth認証付きSMTPサーバーを使用
  - 空文字列: 環境変数（.env）の設定を使用
- SMTPモード選択時、ホストとポートは必須です
- ローカルモードに切り替えると、SMTP関連設定はリセットされます
- sendmailオプションのデフォルトは `-t -i`（非同期）です
- 暗号化オプション：`ssl`、`tls`、`null`（暗号化なし）
- 配信先オーバーライドを設定すると、全メールがそのアドレスに送信されます（テスト用）

---

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

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

### 推奨読解順序

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

メール設定はsystem_configテーブルに保存されます。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | SystemConfigDefinition.php | `src/Core/System/SystemConfig/` | システム設定エンティティの定義 |
| 1-2 | SystemConfigService.php | `src/Core/System/SystemConfig/` | システム設定の読み書きサービス |

**読解のコツ**: メール設定は`core.mailerSettings.*`プレフィックスのキーで保存されます。

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

モジュール登録とルーティング設定を確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | index.js | `src/Administration/Resources/app/administration/src/module/sw-settings-mailer/index.js` | モジュール登録、ルート定義、権限設定 |

**主要処理フロー**:
1. **10-36行目**: Module.registerでモジュール登録
2. **19-28行目**: routes定義（indexのみ）
3. **30-35行目**: settingsItem定義（設定メニューへの追加、systemグループ）

#### Step 3: メール設定画面コンポーネントを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | index.js | `src/Administration/Resources/app/administration/src/module/sw-settings-mailer/page/sw-settings-mailer/index.js` | メール設定画面のロジック |

**主要処理フロー**:
- **7-18行目**: defaultMailerSettings - デフォルト設定値
- **46-57行目**: emailSendmailOptions - sendmailオプション
- **59-64行目**: isSmtpMode - SMTPモード判定
- **66-89行目**: emailAgentOptions - メールエージェントオプション
- **97-104行目**: createdComponent() - 初期化処理
- **106-119行目**: loadMailerSettings() - 設定読み込み
- **121-153行目**: saveMailerSettings() - 設定保存
- **163-176行目**: validateSmtpConfiguration() - SMTPバリデーション

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

```
sw-settings-mailer (モジュール)
    │
    └─ sw-settings-mailer (設定画面)
           ├─ systemConfigApiService.getValues() - 設定読み込み
           ├─ validateSmtpConfiguration() - SMTPバリデーション
           │     ├─ smtpHostError 設定
           │     └─ smtpPortError 設定
           ├─ systemConfigApiService.saveValues() - 設定保存
           └─ sw-settings-mailer-smtp (SMTPコンポーネント)
                  └─ SMTP詳細設定UI
```

### データフロー図

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

メール設定フォーム ──▶ sw-settings-mailer ────────────▶ system_config テーブル
                              │
メールエージェント選択 ──▶    ├─▶ isSmtpMode 判定
                              │     └─▶ SMTP/sendmail設定表示切替
                              │
SMTP設定入力 ────────▶        ├─▶ validateSmtpConfiguration()
                              │     └─▶ host/portバリデーション
                              │
                              └─▶ systemConfigApiService.saveValues()
                                        │
                                        ▼
                              Admin API (/api/_action/system-config)
                                        │
                                        ▼
                              SystemConfigService (PHP)
                                        │
                                        ▼
                              system_config テーブル
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| index.js | `src/Administration/Resources/app/administration/src/module/sw-settings-mailer/index.js` | ソース | モジュール定義 |
| index.js | `src/Administration/Resources/app/administration/src/module/sw-settings-mailer/page/sw-settings-mailer/index.js` | ソース | 設定画面ロジック |
| sw-settings-mailer.html.twig | `src/Administration/Resources/app/administration/src/module/sw-settings-mailer/page/sw-settings-mailer/sw-settings-mailer.html.twig` | テンプレート | 設定画面UI |
| sw-settings-mailer.scss | `src/Administration/Resources/app/administration/src/module/sw-settings-mailer/page/sw-settings-mailer/sw-settings-mailer.scss` | スタイル | 設定画面スタイル |
| index.js | `src/Administration/Resources/app/administration/src/module/sw-settings-mailer/component/sw-settings-mailer-smtp/index.js` | ソース | SMTPコンポーネント |
