# 画面設計書 59-メールテンプレート

## 概要

本ドキュメントは、Shopware 6 管理画面におけるメールテンプレート（sw-mail-template）画面の設計書です。ECサイトから送信されるメールのテンプレートおよびヘッダー/フッターの登録・編集・管理を行う画面について記述します。

### 本画面の処理概要

**業務上の目的・背景**：ECサイトでは注文確認、発送通知、パスワードリセットなど、様々なメールを顧客に送信します。本画面では、これらのメールのテンプレート（HTML/プレーンテキスト）を管理し、メール内容のカスタマイズ、テストメール送信、メディア添付ファイルの設定を行います。

**画面へのアクセス方法**：管理画面にログイン後、左メニューの「設定」 > 「メールテンプレート」をクリックして一覧画面にアクセスします。一覧画面からテンプレート名をクリックして詳細画面に遷移します。

**主要な操作・処理内容**：
1. メールテンプレート一覧の表示・検索
2. 新規メールテンプレートの作成
3. 既存メールテンプレートの編集（件名、送信者名、HTML/プレーンテキスト本文）
4. メールプレビューの表示
5. テストメールの送信
6. メディア添付ファイルの設定
7. 利用可能な変数の参照・挿入
8. メールヘッダー/フッターの管理

**画面遷移**：設定メニュー → メールテンプレート一覧画面（テンプレートタブ/ヘッダー・フッタータブ） → メールテンプレート詳細画面。詳細画面から一覧画面への戻り遷移も可能です。

**権限による表示制御**：`mail_templates.viewer`権限で閲覧可能、`mail_templates.editor`権限で編集可能、`mail_templates.creator`権限で新規作成可能、`mail_templates.deleter`権限で削除可能です。テストメール送信には`api_send_email`権限が必要です。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 58 | メール設定 | 関連 | メールサーバー設定 |

## 画面種別

一覧 / 詳細 / 登録 / 編集

## URL/ルーティング

| 画面 | URL | コンポーネント |
|------|-----|---------------|
| メールテンプレート一覧（テンプレート） | `#/sw/mail/template/index/templates` | sw-mail-template-view-templates |
| メールテンプレート一覧（ヘッダー・フッター） | `#/sw/mail/template/index/header-footer` | sw-mail-template-view-header-footer |
| メールテンプレート詳細 | `#/sw/mail/template/detail/:id` | sw-mail-template-detail |
| メールテンプレート新規作成 | `#/sw/mail/template/create` | sw-mail-template-create |
| ヘッダー・フッター詳細 | `#/sw/mail/template/detail-head-foot/:id` | sw-mail-header-footer-detail |
| ヘッダー・フッター新規作成 | `#/sw/mail/template/create-head-foot` | sw-mail-header-footer-create |

## 入出力項目

### メールテンプレート詳細画面

| 項目名 | 項目ID | 型 | 入力/出力 | 必須 | 説明 |
|--------|--------|-----|----------|------|------|
| テンプレートタイプ | mailTemplateTypeId | uuid | 入力 | ○ | メールテンプレートの種類 |
| 件名 | subject | string | 入力 | ○ | メールの件名 |
| 送信者名 | senderName | string | 入力 | ○ | メール送信者の表示名 |
| 説明 | description | text | 入力 | - | テンプレートの説明 |
| HTML本文 | contentHtml | text | 入力 | ○ | メールのHTML本文 |
| プレーンテキスト本文 | contentPlain | text | 入力 | ○ | メールのプレーンテキスト本文 |

### テストメール送信

| 項目名 | 項目ID | 型 | 入力/出力 | 必須 | 説明 |
|--------|--------|-----|----------|------|------|
| テストメールアドレス | testerMail | string | 入力 | ○ | テストメール送信先 |
| 販売チャネル | testMailSalesChannelId | uuid | 入力 | ○ | テストメール用販売チャネル |

## 表示項目

### 一覧画面

| 項目名 | 説明 |
|--------|------|
| テンプレート名 | メールテンプレートタイプの名前 |
| 件名 | メールの件名 |
| 説明 | テンプレートの説明 |

### 詳細画面

| 項目名 | 説明 |
|--------|------|
| 基本情報 | テンプレートタイプ、件名、送信者名、説明 |
| HTMLエディター | HTML本文の編集（ACEエディター、変数自動補完付き） |
| プレーンテキストエディター | プレーンテキスト本文の編集 |
| 利用可能な変数 | テンプレートタイプに応じた変数一覧（ツリー表示） |
| メディア添付 | 添付ファイルの一覧・追加・削除 |
| テストメール | テストメール送信フォーム |
| プレビュー | レンダリング後のメールプレビュー |

## イベント仕様

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

ユーザーが「保存」ボタンを押下すると、入力されたテンプレート情報がバリデーションされ、mailTemplateリポジトリを通じてAPIに保存リクエストが送信されます。保存成功時は成功通知が表示されます。

### 2-キャンセルボタン押下

ユーザーが「キャンセル」ボタンを押下すると、変更を破棄してメールテンプレート一覧画面に遷移します。

### 3-テストメール送信

テストメールアドレスと販売チャネルを入力し、「テストメールを送信」ボタンを押下すると、mailService.testMailTemplateを通じてテストメールが送信されます。送信成功/失敗の通知が表示されます。

### 4-プレビュー表示

「プレビューを表示」ボタンを押下すると、mailService.buildRenderPreviewを通じてレンダリング後のメールプレビューがモーダルで表示されます。

### 5-変数コピー

利用可能な変数一覧から変数名をクリックすると、dom.copyStringToClipboardを通じてクリップボードにコピーされます。

### 6-メディア添付追加

メディアをアップロードまたはメディアサイドバーから選択すると、mail_template_mediaエンティティが作成されてテンプレートに関連付けられます。

### 7-テンプレートタイプ変更

テンプレートタイプを変更すると、onChangeTypeが呼び出され、利用可能な変数一覧が更新されます。

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| 保存ボタン押下 | mail_template | INSERT/UPDATE | メールテンプレート情報の新規作成または更新 |
| 保存ボタン押下 | mail_template_translation | INSERT/UPDATE | メールテンプレートの翻訳情報 |
| メディア添付追加 | mail_template_media | INSERT | メディア添付の関連付け |
| メディア添付削除 | mail_template_media | DELETE | メディア添付の削除 |
| 削除ボタン押下 | mail_template | DELETE | メールテンプレートの削除 |

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

#### mail_template

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| INSERT/UPDATE | id | UUIDv4 | 新規作成時は自動生成 |
| INSERT/UPDATE | mail_template_type_id | 選択値 | テンプレートタイプへの外部キー |
| INSERT/UPDATE | subject | 入力値 | メール件名 |
| INSERT/UPDATE | sender_name | 入力値 | 送信者名 |
| INSERT/UPDATE | description | 入力値 | 説明 |
| INSERT/UPDATE | content_html | 入力値 | HTML本文 |
| INSERT/UPDATE | content_plain | 入力値 | プレーンテキスト本文 |

#### mail_template_media

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| INSERT | id | UUIDv4 | 自動生成 |
| INSERT | mail_template_id | 親テンプレートのID | 外部キー |
| INSERT | language_id | 現在の言語ID | 言語別添付ファイル |
| INSERT | media_id | メディアのID | 外部キー |
| INSERT | position | 数値 | 添付ファイルの順序 |

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 | 表示条件 |
|------------|------|--------------|----------|
| notificationTestMailSuccessMessage | 成功 | テストメールが正常に送信されました | テストメール送信成功時 |
| notificationTestMailErrorMessage | エラー | テストメールの送信に失敗しました | テストメール送信失敗時 |
| notificationTestMailSalesChannelErrorMessage | エラー | 販売チャネルを選択してください | 販売チャネル未選択時 |
| notificationSyntaxValidationErrorMessage | エラー | テンプレート構文にエラーがあります: {errorMsg} | テンプレート構文エラー時 |
| missingMailTemplateTypeErrorMessage | エラー | メールテンプレートタイプが見つかりません | タイプ未設定時 |
| messageSaveError | エラー | メールテンプレート「{subject}」の保存に失敗しました | 保存失敗時 |
| errorMediaItemDuplicated | 情報 | このメディアは既に添付されています | 重複メディア追加時 |

## 例外処理

| 例外ケース | 処理内容 |
|-----------|---------|
| メールテンプレートが見つからない | エラー通知を表示し、一覧画面にリダイレクト |
| テンプレートタイプが見つからない | missingMailTemplateTypeErrorMessageを表示 |
| 権限不足 | 該当するアクションボタンを無効化し、ツールチップで警告表示 |
| api_send_email権限なし | テストメール送信ボタンを無効化 |
| 通信エラー | エラー通知を表示し、ローディング状態を解除 |
| テンプレート構文エラー | notificationSyntaxValidationErrorMessageを表示 |
| 販売チャネル言語不一致 | showLanguageNotAssignedToSalesChannelWarningを表示 |

## 備考

- メールテンプレートはTwigテンプレートエンジンを使用してレンダリングされます
- 利用可能な変数はテンプレートタイプに依存し、templateDataから動的に取得されます
- 変数参照時に`.at(0)`形式や`.first`形式がサポートされています
- メディア添付ファイルは言語別に管理されます（languageId）
- ACEエディターは基本的な自動補完機能をサポートしています
- プレビュー機能はレンダリング後のHTMLを表示します
- テストメール送信には件名、プレーンテキスト本文、HTML本文、送信者名が必須です

---

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

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

### 推奨読解順序

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

メールテンプレートエンティティとその関連データの構造を理解することが重要です。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | MailTemplateDefinition.php | `src/Core/Content/MailTemplate/` | メールテンプレートエンティティの定義 |
| 1-2 | MailTemplateTypeDefinition.php | `src/Core/Content/MailTemplate/Aggregate/MailTemplateType/` | テンプレートタイプの定義 |
| 1-3 | MailTemplateMediaDefinition.php | `src/Core/Content/MailTemplate/Aggregate/MailTemplateMedia/` | メディア添付の関連エンティティ |

**読解のコツ**: テンプレートタイプには利用可能なエンティティ（availableEntities）とテンプレートデータ（templateData）が定義されています。

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

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

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

**主要処理フロー**:
1. **33-120行目**: Module.registerでモジュール登録
2. **45-112行目**: routes定義（index、detail、create、ヘッダー・フッター関連）
3. **114-119行目**: settingsItem定義（設定メニューへの追加、contentグループ）

#### Step 3: 詳細画面コンポーネントを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | index.js | `src/Administration/Resources/app/administration/src/module/sw-mail-template/page/sw-mail-template-detail/index.js` | 詳細画面のロジック |

**主要処理フロー**:
- **199-239行目**: createdComponent() - 初期化処理、ExtensionAPI公開
- **242-259行目**: loadEntityData() - テンプレートデータの読み込み
- **309-343行目**: onSave() - 保存処理
- **345-401行目**: onClickTestMailTemplate() - テストメール送信
- **403-432行目**: onClickShowPreview() - プレビュー表示
- **486-512行目**: onChangeType() - テンプレートタイプ変更
- **594-627行目**: loadAvailableVariables() - 利用可能な変数の読み込み

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

```
sw-mail-template (モジュール)
    │
    ├─ sw-mail-template-index (一覧画面)
    │      ├─ sw-mail-template-view-templates (テンプレートタブ)
    │      │      └─ sw-mail-template-list
    │      │             └─ mailTemplateRepository.search()
    │      └─ sw-mail-template-view-header-footer (ヘッダー・フッタータブ)
    │             └─ sw-mail-header-footer-list
    │
    ├─ sw-mail-template-detail (詳細画面)
    │      ├─ mailTemplateRepository.get() - テンプレート取得
    │      ├─ mailTemplateTypeRepository.get() - タイプ取得
    │      ├─ mailTemplateRepository.save() - 保存
    │      ├─ mailService.testMailTemplate() - テストメール送信
    │      ├─ mailService.buildRenderPreview() - プレビュー生成
    │      └─ dom.copyStringToClipboard() - 変数コピー
    │
    └─ sw-mail-header-footer-detail (ヘッダー・フッター詳細)
           ├─ mailHeaderFooterRepository.get() - ヘッダー・フッター取得
           └─ mailHeaderFooterRepository.save() - 保存
```

### データフロー図

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

テンプレートフォーム ──▶ sw-mail-template-detail ─────▶ mail_template テーブル
                              │
テストメール送信 ────▶        ├─▶ mailService.testMailTemplate()
                              │     └─▶ SMTP/sendmail で送信
                              │
プレビュー要求 ───────▶       ├─▶ mailService.buildRenderPreview()
                              │     └─▶ Twig レンダリング
                              │
                              └─▶ mailTemplateRepository.save()
                                        │
                                        ▼
                              Admin API (/api/mail-template)
                                        │
                                        ▼
                              MailTemplateRepository (PHP)
                                        │
                                        ├─▶ mail_template
                                        ├─▶ mail_template_translation
                                        └─▶ mail_template_media
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| index.js | `src/Administration/Resources/app/administration/src/module/sw-mail-template/index.js` | ソース | モジュール定義 |
| index.js | `src/Administration/Resources/app/administration/src/module/sw-mail-template/page/sw-mail-template-detail/index.js` | ソース | 詳細画面ロジック |
| sw-mail-template-detail.html.twig | `src/Administration/Resources/app/administration/src/module/sw-mail-template/page/sw-mail-template-detail/sw-mail-template-detail.html.twig` | テンプレート | 詳細画面UI |
| index.js | `src/Administration/Resources/app/administration/src/module/sw-mail-template/component/sw-mail-template-list/index.js` | ソース | テンプレート一覧コンポーネント |
| index.js | `src/Administration/Resources/app/administration/src/module/sw-mail-template/component/sw-mail-header-footer-list/index.js` | ソース | ヘッダー・フッター一覧コンポーネント |
| index.js | `src/Administration/Resources/app/administration/src/module/sw-mail-template/page/sw-mail-header-footer-detail/index.js` | ソース | ヘッダー・フッター詳細画面 |
| index.js | `src/Administration/Resources/app/administration/src/module/sw-mail-template/acl/index.js` | ソース | 権限定義 |
